From de9f6bc3ff41036b85a51bf567af75b4e2011d3d Mon Sep 17 00:00:00 2001 From: Alex Mikhalev Date: Wed, 18 Feb 2026 14:01:38 +0100 Subject: [PATCH] docs: Update handover and add lessons learned - Update HANDOVER.md with AI agent skill section, API gotchas, session log - Add lessons-learned.md with Gitea API findings and debugging insights Co-Authored-By: Claude Opus 4.6 --- HANDOVER.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++ lessons-learned.md | 65 +++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 lessons-learned.md diff --git a/HANDOVER.md b/HANDOVER.md index 4e985c5..1c0b6a9 100644 --- a/HANDOVER.md +++ b/HANDOVER.md @@ -203,6 +203,66 @@ To update Gitea to a new version: See `MIRRORING-GUIDE.md` for bidirectional GitHub ↔ Gitea mirroring setup. +## AI Agent Skill (Gitea Task Management) + +Added 2026-02-18. Provides AI agents with project and task management via Gitea API. + +### Architecture + +Dual-mode: gitea-mcp (75+ tools for standard CRUD) + curl/jq shell helpers (milestones, workflow labels, dependencies -- areas where gitea-mcp has gaps). + +### Key Constraint + +Gitea 1.22.6 has NO project board REST API. Milestones serve as project containers with built-in progress tracking. + +### Files + +| File | Description | +|------|-------------| +| `.agents/skills/gitea/SKILL.md` | Agent skill document with all helpers | +| `.agents/skills/gitea/setup-labels.sh` | Idempotent repo + 12 label creation | +| `.agents/skills/gitea/test-gitea-skill.sh` | 10 integration tests (26 assertions) | +| `.docs/RESEARCH-gitea-agent-skill.md` | Phase 1 research (verified against live) | +| `.docs/DESIGN-gitea-agent-skill.md` | Phase 2 design document | + +### Default Task Repository + +`terraphim/agent-tasks` -- overridable via `GITEA_OWNER` and `GITEA_REPO` env vars. + +### Authentication + +```bash +source ~/op_zesticai_non_prod.sh +export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential") +``` + +### Workflow Labels + +12 scoped labels across 3 scopes (workflow, priority, type). Workflow state machine: `ready -> in-progress -> blocked -> done`. + +### Running Tests + +```bash +source ~/op_zesticai_non_prod.sh +export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential") +.agents/skills/gitea/test-gitea-skill.sh +``` + +All 26 assertions pass against live Gitea 1.22.6 as of 2026-02-18. + +### Critical API Gotchas + +1. **Label exclusivity is UI-only** -- API POST `/labels` just appends. Must use PUT with label swap pattern (get current, filter `workflow:*`, add new, PUT all). +2. **Assignees** -- Use `PATCH /issues/{index}` with `{"assignees": [...]}`. The `POST /issues/{index}/assignees` endpoint does not exist in 1.22.6. +3. **Issue dependencies** -- Body uses `IssueMeta` format: `{"owner": "...", "repo": "...", "index": N}` (NOT `{"depends_on_id": N}`). + +## Pre-commit Hooks + +Added `.pre-commit-config.yaml` with: +- Trailing whitespace, end-of-file fixer, YAML/JSON check +- Merge conflict and private key detection +- Secret detection via `detect-secrets` (baseline at `.secrets.baseline`) + ## Key Files | File | Description | @@ -213,6 +273,31 @@ See `MIRRORING-GUIDE.md` for bidirectional GitHub ↔ Gitea mirroring setup. | `s3_config.json.template` | SeaweedFS S3 config template | | `prometheus/prometheus.yml` | Prometheus scrape config | | `.github/workflows/*.yml` | GitHub Actions for mirroring | +| `.agents/skills/gitea/SKILL.md` | AI agent Gitea skill | +| `.agents/skills/gitea/setup-labels.sh` | Label setup script | +| `.agents/skills/gitea/test-gitea-skill.sh` | Integration tests | +| `.pre-commit-config.yaml` | Pre-commit hook config | + +## Session Log (2026-02-18) + +### Completed +- Rewrote Gitea agent skill with verified API patterns (milestones, workflow labels, dependencies) +- Created setup-labels.sh for idempotent repo + label creation +- Created test-gitea-skill.sh with 10 tests (26 assertions), all passing +- Found and fixed 3 API behavior bugs (label exclusivity, assignee endpoint, dependency format) +- Added pre-commit hooks and fixed trailing whitespace across 15 files +- Conducted disciplined research and design phases with live API verification + +### Commits (unpushed) +- `b67284e` chore: Fix trailing whitespace across project files +- `66b305d` feat(gitea-skill): Add integration tests and fix workflow label swap +- `1fd202d` feat(gitea-skill): Rewrite Gitea agent skill with verified API patterns + +### Next Steps +1. Push 3 commits to origin/main +2. Consider adding gitea-mcp or forgejo-mcp as MCP server for Claude Code (see SKILL.md MCP Integration section) +3. Create first real milestone and tasks in `terraphim/agent-tasks` for a project +4. Consider Phase 4 (disciplined-verification) if more rigorous validation is needed ## Contacts diff --git a/lessons-learned.md b/lessons-learned.md new file mode 100644 index 0000000..c707d9b --- /dev/null +++ b/lessons-learned.md @@ -0,0 +1,65 @@ +# Lessons Learned + +## Session: 2026-02-18 -- Gitea Agent Skill Implementation + +### Technical Discoveries + +1. **Gitea 1.22.6 has no project board REST API** + - `/api/v1/user/projects` returns 404 + - The existing SKILL.md had endpoints that do not exist + - Project board API is tracked in Gitea issue #14299, targeted for 1.26+ + - **Mitigation:** Use milestones as project containers -- they have built-in progress tracking + +2. **Scoped label exclusivity is UI-only in Gitea 1.22.6** + - Labels with `exclusive: true` display mutual exclusivity in the web UI + - The API `POST /repos/{owner}/{repo}/issues/{index}/labels` only appends -- it does NOT remove conflicting scoped labels + - **Fix:** Use a swap pattern: GET current labels, filter out old scope, add new label ID, PUT full set atomically + - This was the single biggest "gotcha" -- the documentation implies API enforcement that does not exist + +3. **POST /issues/{index}/assignees does not exist in Gitea 1.22.6** + - Returns 404 + - **Fix:** Use `PATCH /repos/{owner}/{repo}/issues/{index}` with `{"assignees": ["username"]}` + - This is a general issue edit endpoint, not a dedicated assignee endpoint + +4. **Issue dependency format is IssueMeta, not simple ID** + - Wrong: `{"depends_on_id": 2}` -- returns "repository does not exist [id: 0]" + - Correct: `{"owner": "terraphim", "repo": "agent-tasks", "index": 2}` + - Must check the Swagger spec for exact body format rather than guessing + +### Debugging Approaches That Worked + +1. **Test against live API first, then write code** + - Verified all 7 open questions against the live Gitea instance before writing any helper functions + - This caught the project board API gap before writing fake endpoints + +2. **Integration tests with real cleanup** + - Each test run creates a timestamped repo (`skill-test-{timestamp}`), runs all tests, then deletes it + - Trap on EXIT ensures cleanup even on failure + - No mocks -- tests prove the actual API behavior + +3. **Incremental testing (run, fail, fix, rerun)** + - First test run: 23/26 pass, 3 fail -- immediately identified the label/assignee issues + - Fixed the swap pattern and PATCH approach, second run: 26/26 pass + +### Pitfalls to Avoid + +1. **Do not trust Gitea documentation for API behavior** -- always verify against the live instance. The swagger spec is the source of truth, but even that can be misleading for edge cases like scoped label exclusivity. + +2. **Do not assume POST endpoints exist for every resource subpath** -- Gitea's API is inconsistent. Some resources (labels) have POST, others (assignees) only work via PATCH on the parent resource. + +3. **Do not rely on UBS scanner for infrastructure projects** -- UBS found no scannable language files (expected for a project with only shell scripts, YAML, and markdown). Pre-commit hooks are more useful here. + +4. **Pre-commit python version** -- The system may not have the Python version specified in `.pre-commit-config.yaml`. Changed from `python3.9` to `python3.12` to match the system. Also needed `python3.12-venv` apt package for virtualenv support. + +### Best Practices Discovered + +1. **Disciplined development phases work well for API integration** + - Phase 1 (Research): Discovered the project board API gap before design + - Phase 2 (Design): Created the label swap architecture before implementation + - Phase 3 (Implementation): Tests caught 3 API bugs on first run + +2. **Default repository pattern** -- Using env vars with defaults (`GITEA_OWNER=${GITEA_OWNER:-terraphim}`) lets agents work out of the box while remaining configurable. + +3. **JSON output from all helpers** -- Every shell function outputs valid JSON, making it trivial for agents to parse results with jq. + +4. **Idempotent setup scripts** -- `setup-labels.sh` checks for existing resources before creating, making it safe to run repeatedly.