From 1790a724bd48b1a67a116bac6aab7a0a190348e3 Mon Sep 17 00:00:00 2001 From: emil Date: Sat, 5 Sep 2026 16:14:02 +0200 Subject: [PATCH] docs: add dependency-graph, deployment-coordination, and skill-creation skills Closes DEVX-167 --- .devin/skills/dependency-graph/SKILL.md | 135 +++++++++++++++++ .../skills/deployment-coordination/SKILL.md | 90 +++++++++++ .devin/skills/skill-creation/SKILL.md | 142 ++++++++++++++++++ docs/specs/DEVX-167.md | 64 ++++++++ 4 files changed, 431 insertions(+) create mode 100644 .devin/skills/dependency-graph/SKILL.md create mode 100644 .devin/skills/deployment-coordination/SKILL.md create mode 100644 .devin/skills/skill-creation/SKILL.md create mode 100644 docs/specs/DEVX-167.md diff --git a/.devin/skills/dependency-graph/SKILL.md b/.devin/skills/dependency-graph/SKILL.md new file mode 100644 index 0000000..c6c8591 --- /dev/null +++ b/.devin/skills/dependency-graph/SKILL.md @@ -0,0 +1,135 @@ +# dependency-graph + +Map of the oblachno ecosystem. Knows which repo produces what, which +repos depend on which, and the correct order for cross-repo changes. + +## When to Invoke + +Invoke this skill when: +- Changes span multiple repos +- A change in one repo requires version bumps in downstream repos +- Deploying infrastructure that depends on published packages/images +- Verifying the ecosystem is in a consistent state before deployment +- Determining which repos to update and in what order + +## Prerequisites + +- All repos cloned under `/home/emo/dev/ideas/oblachno/` +- `.env` with `DEVELOPER_GITEA_API_TOKEN` in each repo + +## Ecosystem Map + +``` + devx (PyPI package) + / | \ + / | \ + grm sso-bridge infra + (PyPI) (PyPI+Docker) (deploys all) + | | | + v v v + infra bump infra bump staging + (auto PR) (auto PR) production + | + mattermost-oidc (Docker image) + (infra pulls :latest at deploy) +``` + +## Repositories + +| Repo | Produces | Consumers | Release Trigger | +|------|----------|-----------|-----------------| +| `devx` | PyPI package `devx` | grm, sso-bridge, infra | User-facing changes to `src/devx/**` | +| `grm` | PyPI package `grm` | infra | User-facing changes to `src/grm/**` or `ansible/**` | +| `sso-bridge` | PyPI package `sso_bridge` + Docker image | infra | User-facing changes to `src/sso_bridge/**` or `ansible/**` | +| `infra` | Staging/production deployment | (end users) | User-facing changes + nightly gate | +| `mattermost-oidc` | Docker image `mattermost-oidc` | infra (pulls at deploy) | `Dockerfile` or `build.yml` changes | + +## Dependency Chain + +### devx → all repos + +devx publishes to the Gitea PyPI registry. grm, sso-bridge, and infra +pin devx in `pyproject.toml`: +```toml +"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@vX.Y.Z" +``` + +When devx publishes a new version: +1. grm, sso-bridge, and infra must bump their pinned devx version +2. This is currently manual — no auto-dependency-PR from devx +3. Each repo must `make setup` to pick up the new version + +### grm → infra + +grm publishes to PyPI. Its post-merge workflow auto-creates an infra +dependency PR via `devx.ci.create_dependency_pr --repo oblachno/infra +--package grm`. The PR bumps the pinned grm version in infra's +`pyproject.toml`. + +### sso-bridge → infra + +sso-bridge publishes to PyPI AND builds a Docker image. Its post-merge +workflow auto-creates an infra dependency PR via +`devx.ci.create_dependency_pr --repo oblachno/infra --package +sso_bridge`. The PR bumps the pinned sso_bridge version. + +The Docker image is pulled by infra at deploy time (`sso-bridge:latest`). + +### mattermost-oidc → infra + +mattermost-oidc builds a Docker image tagged `:latest` and `:MM_VERSION`. +infra pulls `mattermost-oidc:latest` at deploy time. There is no +auto-dependency-PR — infra simply pulls the latest image. + +### infra → staging/production + +infra deploys to staging and production. The deployment: +1. Provisions VMs from golden images +2. Runs Ansible roles (including grm and sso-bridge roles) +3. Pulls Docker images (sso-bridge, mattermost-oidc) +4. Configures services + +## Correct Order for Cross-Repo Changes + +When a change spans multiple repos, follow this order: + +1. **devx first** — if the change starts in devx, merge and publish devx + first. Wait for the PyPI publish job to complete. +2. **Bump devx in consumers** — in grm/sso-bridge/infra, bump the pinned + devx version, run `make setup`, verify tests pass, merge. +3. **grm/sso-bridge second** — merge and publish grm/sso-bridge. Wait + for the PyPI publish + Docker image build to complete. +4. **Auto-dependency-PRs** — grm/sso-bridge post-merge auto-creates infra + PRs to bump pinned versions. Wait for these PRs to appear. +5. **Merge infra dependency PRs** — review and merge the auto-created + infra PRs. +6. **infra last** — deploy to staging, validate, promote to production. + +## State Verification Before Deployment + +Before deploying infra, verify: + +1. **devx version consistent** — all repos pin the same devx version +2. **grm published** — latest grm tag exists in PyPI +3. **sso-bridge published** — latest sso_bridge tag exists in PyPI +4. **sso-bridge image built** — latest sso-bridge Docker image exists +5. **mattermost-oidc image built** — latest mattermost-oidc image exists +6. **infra pins match published versions** — no stale pins +7. **Nightly gate green** — `NIGHTLY_STATUS` is not `failed` + +## Quick Check Commands + +```bash +# Check latest devx version +curl -sS https://git.oblachno.oblachno.fyi/api/v1/repos/oblachno-oss/devx/releases/latest | python3 -c "import json,sys; print(json.load(sys.stdin).get('tag_name','?'))" + +# Check pinned devx version in each repo +for repo in grm sso-bridge infra; do + echo -n "$repo: "; grep 'devx @' /home/emo/dev/ideas/oblachno/$repo/pyproject.toml | grep -oP 'v[\d.]+' +done + +# Check latest sso-bridge image build +curl -sS -H "Authorization: token $DEVELOPER_GITEA_API_TOKEN" \ + "https://git.oblachno.oblachno.fyi/api/v1/repos/oblachno/sso-bridge/actions/runs?per_page=5" \ + | python3 -c "import json,sys; [print(r['id'],r['status'],r['conclusion']) for r in json.load(sys.stdin).get('workflow_runs',[]) if r.get('event')=='push']" +``` diff --git a/.devin/skills/deployment-coordination/SKILL.md b/.devin/skills/deployment-coordination/SKILL.md new file mode 100644 index 0000000..6f1e791 --- /dev/null +++ b/.devin/skills/deployment-coordination/SKILL.md @@ -0,0 +1,90 @@ +# deployment-coordination + +How devx releases propagate to downstream repos. devx is the base +package — all other repos pin it. A devx release must complete before +consumers can bump. + +## When to Invoke + +Invoke this skill when: +- Changes to devx affect downstream repos (grm, sso-bridge, infra) +- Preparing a devx release that other repos depend on +- Verifying downstream repos have bumped to the latest devx version +- Coordinating a multi-repo change that starts in devx + +## Prerequisites + +- devx repo at `/home/emo/dev/ideas/oblachno/devx` +- `.env` with `DEVELOPER_GITEA_API_TOKEN` +- See `dependency-graph` skill for the full ecosystem map + +## What devx Produces + +devx publishes a Python package to the Gitea PyPI registry. Downstream +repos pin it: +```toml +"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@vX.Y.Z" +``` + +## Release Flow + +1. PR merged to master +2. Post-merge workflow runs `devx.ci.release` — classifies changes +3. If user-facing changes: git-cliff bumps version, creates tag, pushes +4. `devx.ci.publish` builds and publishes to Gitea PyPI registry +5. Downstream repos must bump their pinned devx version + +## Downstream Consumers + +| Repo | Pin location | Auto-bump? | +|------|-------------|------------| +| grm | `pyproject.toml` | No — manual | +| sso-bridge | `pyproject.toml` | No — manual | +| infra | `pyproject.toml` | No — manual | + +devx does NOT auto-create dependency PRs in downstream repos. Bumping +is manual: create a PR in each downstream repo to update the pinned +version. + +## Coordinating a devx Change + +When a change to devx affects downstream repos: + +1. **Merge devx PR** — wait for post-merge publish to complete +2. **Verify publish** — check the new tag exists: + ```bash + curl -sS -H "Authorization: token $DEVELOPER_GITEA_API_TOKEN" \ + https://git.oblachno.oblachno.fyi/api/v1/repos/oblachno-oss/devx/releases/latest \ + | python3 -c "import json,sys; print(json.load(sys.stdin).get('tag_name','?'))" + ``` +3. **Bump downstream repos** — for each repo (grm, sso-bridge, infra): + - Update `devx @ ...@vX.Y.Z` in `pyproject.toml` + - Run `make setup` to install the new version + - Run `make pytest-cov` to verify compatibility + - Create and merge a PR +4. **Verify infra deploys** — after infra bumps, verify staging deploy + picks up the new devx version + +## State Verification + +Before starting a devx change, verify current state: +```bash +# Current devx version +grep '__version__' /home/emo/dev/ideas/oblachno/devx/src/devx/__init__.py + +# What each repo pins +for repo in grm sso-bridge infra; do + echo -n "$repo pins: " + grep 'devx @' /home/emo/dev/ideas/oblachno/$repo/pyproject.toml | grep -oP 'v[\d.]+' +done +``` + +If pins are inconsistent across repos, bump them to the latest published +version before starting new work. + +## Common Mistakes + +- Merging a devx PR and immediately merging downstream PRs without + waiting for the publish job to complete +- Forgetting to bump infra (it has the most complex deploy pipeline) +- Bumping only one downstream repo when the change affects all three diff --git a/.devin/skills/skill-creation/SKILL.md b/.devin/skills/skill-creation/SKILL.md new file mode 100644 index 0000000..1053a48 --- /dev/null +++ b/.devin/skills/skill-creation/SKILL.md @@ -0,0 +1,142 @@ +# skill-creation + +How to create, validate, and maintain Devin skills. Skills must be +clear, succinct, and actionable — no AI slop. + +## When to Invoke + +Invoke this skill when: +- Creating a new skill +- Amending an existing skill +- Evaluating whether a skill is needed +- Reviewing a PR that adds or modifies skills + +## Prerequisites + +- Skill directory: `.devin/skills//SKILL.md` +- Validator: `tests/test_skills.py` (infra) or reference to it +- Tests: `tests/unit/test_skills_validation.py` (infra) + +## When to Create a Skill + +Create a skill when: +- An agent struggles with a task repeatedly (branch hygiene, PR order) +- A workflow has non-obvious ordering constraints (deployment coordination) +- A task requires specific tool usage over raw commands (CI monitoring) +- Multiple agents need shared context (dependency graph) + +Do NOT create a skill for: +- One-off tasks (use a spec instead) +- Tasks already covered by AGENTS.md +- Tasks that are obvious from the Makefile or README +- Tasks that change frequently (skills should be stable) + +## Skill Structure + +Every skill MUST have: + +```markdown +# + +One-line description of what the skill does. + +## When to Invoke + +2-4 bullet points describing when to use this skill. + +## Prerequisites + +What must exist before using the skill (venv, .env, tools). + +## + +The actual guidance. Keep it actionable. + +## Verification (if applicable) + +How to verify the skill's guidance works. + +## Common Mistakes (if applicable) + +What agents get wrong without this skill. +``` + +## Quality Standards + +### Do +- **Be specific.** Reference exact make targets, file paths, commands. +- **Be concise.** Each section should be scannable in under 30 seconds. +- **Be actionable.** Every paragraph should tell the agent what to DO. +- **Use tables** for command reference, mappings, and comparisons. +- **Use code blocks** for commands the agent should run. +- **Link to other skills** when related (e.g., "See `dependency-graph` skill"). + +### Don't +- **No preamble.** Don't start with "This skill helps agents..." — just state what it does. +- **No filler.** Don't repeat information from AGENTS.md or other skills. +- **No vague advice.** "Be careful with branches" is useless. "Run `git branch --show-current` before every commit" is useful. +- **No AI slop.** Don't write "In this comprehensive guide, we will explore..." — just give the guidance. +- **No redundant sections.** If "Common Mistakes" would repeat "When to Invoke", skip it. +- **No marketing.** Don't describe the skill as "powerful" or "comprehensive". + +## Scope Rules + +- **One skill per concern.** Don't mix branch hygiene with CI monitoring. +- **Project-specific, not generic.** Skills reference this repo's make targets, file paths, and conventions — not abstract advice. +- **Shared skills must be identical across repos.** Use `SHARED_SKILLS` in the validator to enforce this. +- **Per-repo skills must reflect that repo's reality.** Don't copy infra-specific targets to sso-bridge. + +## Automated Validation + +Every skill must pass the validator (`tests/test_skills.py`). The validator checks: + +1. **Structure** — H1 title, "When to Invoke" section, "Prerequisites" section +2. **Commands** — referenced `make ` commands exist in Makefile or devx.mak +3. **Paths** — referenced file paths exist in the repo +4. **Shared skills** — identical content across repos (SHA-256 comparison) +5. **No drift** — no references to nonexistent commands or files + +Run the validator: +```bash +python3 tests/test_skills.py --repo infra --repo sso-bridge +``` + +## Effectiveness Evaluation + +### Static Checks (automated, CI) + +The validator runs in CI as part of `make pytest-cov`. A failing skill +test blocks the PR. This catches: +- Missing sections +- Invalid commands +- Broken file references +- Cross-repo drift + +### Runtime Metrics (manual, periodic) + +Track these signals to evaluate skill effectiveness: +- **Skill invocation frequency** — how often agents invoke the skill +- **Success rate when invoked** — did the skill prevent the mistake it targets? +- **Feedback issues** — agents create Gitea issues with `feedback` label when a skill is unclear or wrong +- **Mistake recurrence** — if agents still make the mistake the skill targets, the skill needs improvement + +### Retrospective Review + +Periodically (monthly or after major incidents) review skills: +1. List all skills and their last-modified dates +2. Check for feedback issues tagged `skill-improvement` +3. Verify referenced commands still exist (run validator) +4. Remove skills that are no longer relevant +5. Update skills where mistakes still recur +6. Document lessons in this skill's "Common Mistakes" section + +## Creating a New Skill — Checklist + +- [ ] Identify the repeated struggle or non-obvious workflow +- [ ] Check no existing skill covers it +- [ ] Write the skill following the structure above +- [ ] Run `python3 tests/test_skills.py` — must pass +- [ ] Run `make pytest-cov` — must pass with 100% coverage +- [ ] If shared across repos, copy identical content to each repo +- [ ] Add the skill to `SHARED_SKILLS` in the validator if shared +- [ ] Create PR, verify CI passes, merge diff --git a/docs/specs/DEVX-167.md b/docs/specs/DEVX-167.md new file mode 100644 index 0000000..f1186bd --- /dev/null +++ b/docs/specs/DEVX-167.md @@ -0,0 +1,64 @@ +# DEVX-167: Add dependency-graph, deployment-coordination, and skill-creation skills + +## Problem +Agents working across the oblachno ecosystem lack shared, persistent +context for three recurring pain points: + +1. **Cross-repo dependency ordering** — agents frequently merge + downstream PRs before the upstream publish job completes, or forget + to bump infra. There is no single reference for which repo produces + what and in what order changes must propagate. +2. **devx release coordination** — devx is the base package pinned by + grm, sso-bridge, and infra. Agents repeatedly merge devx PRs and + immediately merge downstream bumps without waiting for the PyPI + publish job, or bump only one consumer when a change affects all + three. +3. **Skill quality drift** — skills are created ad hoc with inconsistent + structure, vague advice, and no automated validation reference. New + skills miss required sections, reference nonexistent make targets, + and drift across repos. + +## Approach +Add three SKILL.md files under `.devin/skills/`: + +REQ-1: `dependency-graph` — shared skill mapping the oblachno ecosystem +(repos, what each produces, consumers, release triggers, correct +cross-repo change order, state verification checklist) + +REQ-2: `deployment-coordination` — devx-specific skill covering the +devx release flow, downstream consumers, manual bump procedure, and +common mistakes when coordinating a devx change + +REQ-3: `skill-creation` — shared skill defining skill structure, +quality standards, scope rules, automated validation reference, and a +creation checklist + +## Files Affected +- `.devin/skills/dependency-graph/SKILL.md` (new) +- `.devin/skills/deployment-coordination/SKILL.md` (new) +- `.devin/skills/skill-creation/SKILL.md` (new) +- `docs/specs/DEVX-167.md` (new) + +## Test Plan +- Verify all three SKILL.md files follow the required structure (H1 + title, When to Invoke, Prerequisites sections) +- Verify referenced make targets and file paths exist +- Run `make pytest-cov` — skill validation tests must pass + +## Deploy Plan +- Merge to master; skills are consumed by agents immediately on next + invocation — no build or deploy step required + +## Rollback Plan +- Revert the merge commit; remove the three skill directories + +## Acceptance Criteria +- [x] REQ-1: dependency-graph skill exists with ecosystem map, repo + table, dependency chain, cross-repo change order, and state + verification checklist +- [x] REQ-2: deployment-coordination skill exists with devx release + flow, downstream consumer table, coordination steps, and common + mistakes +- [x] REQ-3: skill-creation skill exists with structure template, + quality standards, scope rules, validation reference, and + creation checklist -- 2.54.0