devx/.devin/skills/devx-workflow/SKILL.md

devx-workflow

Quick reference for devx tools when working on the devx repo itself.

When to Invoke

Invoke this skill when creating PRs, checking CI status, adding labels, rebasing branches, or performing any PR lifecycle operation.

Prerequisites

• .venv exists (run make setup if not)
• .env with DEVELOPER_GITEA_API_TOKEN, VIKUNJA_TOKEN

PR Workflow (use these, not raw git/tea/MCP)

Task	Command
Create Vikunja task	.venv/bin/python -m devx.tools.create_task --title "..." --description "..." (make target doesn't forward args)
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
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

Spec-Driven CI Gates (Pre-merge)

Every PR must pass these gates before merge:

Gate	Module	What it checks
Spec validation	devx.ci.validate_spec	Spec file exists at docs/specs/<TASK-ID>.md, has REQ-IDs, all ACs checked
PR size	devx.ci.check_pr_size	Max 500 lines / 10 files (excludes CHANGELOG, badges, locks)

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