DEVX-105: docs: add devx-workflow skill for agent guidance

2026-07-01 01:10:23 +00:00
parent ad2e59980f
commit b2515bbf37
1 changed files with 37 additions and 0 deletions
@@ -0,0 +1,37 @@
+# devx-workflow
+
+Quick reference for devx tools when working on the devx repo itself.
+
+## PR Workflow (use these, not raw git/tea/MCP)
+
+| Task | Command |
+|------|---------|
+| Create Vikunja task | `make create-task -- --title "..." --description "..."` |
+| Create PR | `make create-pr` |
+| Push + create PR | `make push-with-pr` |
+| Check CI status | `make devx-pr-status` or `make devx-pr-status PR=42 WAIT=1` |
+| Fetch CI failure logs | `make devx-pr-logs` or `make devx-pr-logs PR=42 JOB=quality TAIL=50` |
+| Add ready-to-merge label | `make devx-pr-label` or `make devx-pr-label PR=42` |
+| Post PR review | `make devx-pr-review PR=42 EVENT=APPROVE BODY="..." CHECKLIST=1,2,3,4,5,6,7,8,9,10,11,12,13` |
+| Rebase current branch | `make rebase` |
+| Rebase PR via API | `make pr-rebase` or `make pr-rebase PR=42` |
+
+## Auto-merge Behavior
+
+When the `ready-to-merge` label is added and all CI checks pass:
+1. Auto-merge validates PR title format (`DEVX-N: <vikunja task title>`)
+2. If branch is behind master, auto-merge **rebases via Gitea API** automatically
+3. The rebase triggers a new CI run; the next auto-merge attempt merges
+4. No manual rebase needed unless the API rebase fails
+
+## Key Rules
+
+- Never manually merge via API — always use auto-merge with `ready-to-merge` label
+- Branch naming: `DEVX-N-short-description` (N = Vikunja task ID)
+- Commit format: conventional commits (`feat:`, `fix:`, `docs:`, etc.)
+- PR title: `DEVX-N: <vikunja task title>` (auto-derived by `make create-pr`)
+- 100% test coverage required for all source changes
+- All user-facing strings wrapped in `_()` for i18n
+- Translation keys must be added to `src/devx/translations.json`
+- New CLI commands must be documented in `docs/user/cli-commands.md`
+- New tools must be registered in `src/devx/cli.py` and added to Make targets