Merge pull request #1111 from opsmill/develop

Merge develop into infrahub-develop

Author: ogenstad

.agents/commands/speckit.agent-context.update.md

@@ -0,0 +1,30 @@
+---
+description: Refresh the managed Spec Kit section in coding agent context file(s)
+---
+
+
+<!-- Extension: agent-context -->
+<!-- Config: .specify/extensions/agent-context/ -->
+# Update Coding Agent Context
+
+Refresh the managed Spec Kit section inside the active coding agent's context/instruction file (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`).
+
+## Behavior
+
+The script reads the agent-context extension config at
+`.specify/extensions/agent-context/agent-context-config.yml` to discover:
+
+- `context_file` — the path of the coding agent context file to manage.
+- `context_files` — optional project-relative paths for multiple coding agent context files. When non-empty, the script updates each listed file and the list takes precedence over `context_file`.
+- `context_markers.start` / `.end` — the delimiters surrounding the managed section. Defaults to `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` when the field is missing.
+
+It then creates, replaces, or appends the managed block so that the section points at the most recent plan path when one can be discovered (`specs/<feature>/plan.md`).
+
+If `context_files` and `context_file` are empty, the command reports nothing to do and exits successfully. Context file paths must stay project-relative; absolute paths, Windows drive paths, backslash separators, and `..` path segments are rejected.
+
+## Execution
+
+- **Bash**: `.specify/extensions/agent-context/scripts/bash/update-agent-context.sh [plan_path]`
+- **PowerShell**: `.specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1 [plan_path]`
+
+When `plan_path` is omitted, the script auto-detects the most recently modified `specs/*/plan.md`.

.agents/skills/commit/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: commit
+description: >-
+  Stages and commits the current changes onto a safe working branch, enforcing branch discipline
+  and optionally pushing upstream. TRIGGER when: the user wants to commit, save, or check in the
+  current changes. DO NOT TRIGGER when: opening a pull request → pr.
+argument-hint: Optional `push` to push the branch upstream after committing.
+compatibility: Requires a Git working tree.
+metadata:
+  version: 0.1.0
+  author: OpsMill
+---
+
+# Commit Changes
+
+## Introduction
+
+Stage and commit the current changes onto a safe working branch. This skill enforces branch discipline: when the current branch is unsafe to commit to (the canonical rules live in **step 2** below), it proposes a new `fix/`, `feat/`, `docs/`, etc. branch and switches to it after approval. It works equally well for brand-new work and for additional commits on an existing feature branch. If the user passes `push`, the branch is pushed upstream after the commit.
+
+## Arguments
+
+<arguments> $ARGUMENTS </arguments>
+
+**Supported arguments:**
+
+- `push` — After committing, push the branch upstream (`git push -u origin <branch>` on first push, otherwise `git push`).
+
+## Main Tasks
+
+### 1. Assess Current State
+
+1. Run `git status` to see staged, unstaged, and untracked files.
+2. Run `git branch --show-current` to identify the current branch.
+3. Run `git diff --stat` and `git diff --cached --stat` to summarise the change footprint.
+4. If there are no changes to commit (working tree clean, nothing staged) — STOP and tell the user there's nothing to commit. Do not create an empty commit.
+5. If a merge, rebase, or cherry-pick is in progress (`git status` reports it, or `.git/MERGE_HEAD` / `.git/rebase-*` / `.git/CHERRY_PICK_HEAD` exist) — STOP and surface it to the user rather than committing into the middle of that operation.
+
+### 2. Branch Safety — Never Commit to a Protected or Placeholder Branch
+
+A branch is **unsafe to commit to** if any of the following hold:
+
+- It is the repository's default branch (resolve with `git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null | sed 's@^origin/@@'`, falling back to `git remote show origin | sed -n 's/ *HEAD branch: //p'`).
+- It is a long-standing integration branch by name: `main`, `master`, `stable`, `develop`, `dev`, `trunk`.
+- It is a release branch: matches `release/*`, `release-*`, or is otherwise clearly named `release-something` (e.g. `release-2026.05`, `releases/v3`).
+- It is a placeholder / scratch branch generated by the harness or a worktree — specifically the auto-generated **`adjective-animal`** pattern (e.g. `wary-cuckoo`, `lumbar-gorilla`, `wacky-otter`, `silent-fox`), where the second word is an animal. These exist only to host a session and should not be committed to directly. Be careful **not** to over-match: legitimate two-word branches like `dark-mode`, `rate-limit`, `cache-layer`, or `user-auth` are real feature branches, not scratch branches. When a name is ambiguous (two hyphenated words but not clearly `adjective-animal`), do not assert it is unsafe — instead ask the user "this looks like it might be a generated scratch branch — is it, or is it a real branch you want to commit to?" and proceed on their answer.
+
+If the current branch is unsafe by any of those rules:
+
+1. Do NOT commit on the current branch.
+2. Analyse the changes (diffs from step 1) to understand whether the work is a bug fix or new/extended behaviour.
+3. Propose a branch name using the conventional prefix that matches the change:
+   - **Bug fix** → `fix/<short-description>` (e.g. `fix/graphql-codegen-missing-types`).
+   - **New feature or enhancement** → `feat/<short-description>` (e.g. `feat/add-commit-skill`).
+   - **Docs-only, chore, refactor, etc.** → mirror the conventional-commit type: `docs/<…>`, `chore/<…>`, `refactor/<…>`.
+   - Use a concise kebab-case slug. If the repo has a visible naming convention in `git branch -a` or in `AGENTS.md` / `CONTRIBUTING.md`, follow that instead.
+4. Present the proposed branch name to the user and wait for explicit approval (the user may suggest a different name).
+5. After approval, create and switch to the branch: `git checkout -b <branch-name>`. The uncommitted changes carry across automatically.
+
+If the current branch is already a real feature branch (i.e. not in any of the unsafe categories above), continue on it. Do not create a new branch unless the user explicitly asks for one.
+
+### 3. Stage Changes
+
+1. Review what will be staged. Prefer adding files explicitly by path rather than `git add -A` or `git add .`, especially when untracked files are present — this avoids accidentally committing secrets (`.env`, credentials, key files) or large/generated artefacts.
+2. If staged changes already exist (the user pre-staged), respect that staging and only add additional files when it's clearly intended.
+3. Warn the user and require explicit confirmation before staging any file that looks sensitive (`.env*`, `*secret*`, `*credential*`, `*.key`, `*.pem`) or generated/large (`node_modules/`, build artefacts, `dist/`, `__pycache__/`, lockfiles changed unexpectedly).
+
+### 4. Draft the Commit Message
+
+Follow the repo's conventional-commit style (visible in `git log`):
+
+- Use a type prefix: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`, `ci:`, etc.
+- Optional scope in parentheses: `feat(backend): ...`, `fix(e2e): ...`.
+- Subject line under ~72 characters, imperative mood, no trailing period.
+- Focus on the *why* — what changed in terms of behaviour or capability, not a file list.
+- For multi-area changes, add a short body explaining the motivation.
+- Respect any repo or harness commit-trailer convention (e.g. a `Co-Authored-By` trailer the harness expects to append). Don't strip trailers that are already part of the project's workflow.
+- **Never write a session-link trailer into the commit — strip it if the harness added one.** Some harnesses append a line pointing at the private agent session, e.g. `Claude-Session: https://claude.ai/code/session_…` (or any trailer carrying a URL to an agent, chat, or coding session). These leak an internal, usually unshareable URL into the project's permanent — often public — git history, and they reference session state no future reader can open, so they're pure noise at best and a disclosure at worst. This is the one exception to "don't strip trailers" above: if the harness has inserted such a line, remove it before committing, and never author one yourself. Legitimate project trailers (`Co-Authored-By`, `Signed-off-by`, `Reviewed-by`, etc.) still stay.
+
+Inspect the most recent ~20 commits with `git log --oneline -20` and mirror the style you see (scope conventions, capitalisation, whether bodies are used). Generic examples:
+
+- `fix: correct off-by-one in pagination cursor`
+- `docs: archive completed specs and extract durable knowledge`
+- `feat: add commit skill for safe branch discipline`
+
+Present the proposed commit message to the user before committing. Adjust based on feedback.
+
+### 5. Create the Commit
+
+1. Run `git commit -m "<message>"`. For multi-line messages, use a HEREDOC:
+
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   <subject>
+
+   <body>
+   EOF
+   )"
+   ```
+
+2. Do NOT pass `--no-verify` — let pre-commit hooks run. If a hook fails:
+   - Read the hook output carefully.
+   - Fix the underlying issue (formatting, lint, etc.) rather than bypassing.
+   - Re-stage the fixed files and create a NEW commit so each fix stays traceable. (Don't reach for `--amend` to absorb hook fixes — only amend a commit you deliberately intend to rewrite.)
+3. Run `git status` after the commit to confirm a clean tree and verify success.
+4. Run `git log -1 --stat` so the user can see what landed.
+
+### 6. Push Upstream (only when `push` argument is provided)
+
+**Skip this phase entirely if `push` was NOT passed.**
+
+When `push` IS provided:
+
+1. Re-verify the branch is not unsafe per the rules in step 2 (defence in depth, though step 2 should have prevented this).
+2. Check whether the branch already tracks a remote:
+   - `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null`
+3. If no upstream exists: `git push -u origin <branch-name>`.
+4. If an upstream exists: `git push`.
+5. **Never use `--force` or `--force-with-lease`** unless the user explicitly asks for it. Regular `git push` will fail if the remote has diverged — surface that error to the user instead of overwriting.
+6. Report the push result and, if a remote URL is configured (`git config --get remote.origin.url`), the branch URL the user can open.
+
+## Quality gates
+
+Per `../quality-gates/gates/gate-model.md`. `commit` is **Tier 1** (mutates a branch, does not ship).
+
+| Gate | Trigger | Tier | Primitives | Pass criteria | On-fail |
+|---|---|---|---|---|---|
+| Branch-safety | before commit | T1 | P1 | Paste `git rev-parse --abbrev-ref HEAD` proving HEAD is not a protected/release/scratch branch. | STOP; create a feature branch first |
+
+## Notes
+
+**Branch Safety:**
+
+- The canonical list of unsafe branches lives in **step 2** — that is the single source of truth; don't re-derive it from memory.
+- If asked to override the rule, refuse and explain — the user can switch branches themselves first if they truly intend to commit there (in which case this skill no longer applies).
+
+**This is a discipline skill — hold the line under pressure.** Refusing to commit to a protected branch is the whole point, and the excuses below will appear. None of them change where the commit should land:
+
+| Excuse / pressure | Reality |
+|-------------------|---------|
+| "It's urgent / it's an emergency, just commit to main." | Urgency doesn't change where the commit lands. A `feat/`/`fix/` branch takes seconds and is just as fast to merge. |
+| "Just this once, skip the branch." | There is no "just once" — the rule exists precisely for the tempting one-off. Propose a branch. |
+| "It's a tiny change, the branch is overkill." | Size is irrelevant to branch safety; a one-line fix on `main` is still a direct commit to a protected branch. |
+| "The hook is failing, just use `--no-verify`." | Fix the violation instead. Bypassing the hook defeats its purpose. |
+| "The remote diverged, just `--force`." | Never force-push unless the user explicitly asks. Surface the divergence instead. |
+
+Red-flags self-check — if you catch yourself thinking any of these, STOP and re-read step 2:
+
+- "This branch is *probably* fine to commit to."
+- "I'll commit here and sort the branch out later."
+- "The user clearly wants this on `main`, so the rule doesn't apply."
+
+**Secret Hygiene:**
+
+- Prefer explicit `git add <path>` over wholesale `git add -A`.
+- Warn before staging anything that looks like a secret or credential.
+- A session-link trailer (`Claude-Session:` / any agent-session URL) is a disclosure too — strip it from the commit message before committing, per step 4.
+
+**Hook Discipline:**
+
+- Pre-commit hooks exist for good reasons. Fix violations rather than bypassing with `--no-verify`.
+
+**Idempotency:**
+
+- Safe to invoke repeatedly. With no changes to commit, the skill exits cleanly without creating an empty commit.
+
+## Expected Outcome
+
+- All staged/unstaged changes that the user wanted to capture are committed on a safe working branch.
+- The branch is named meaningfully (existing real feature branch preserved, or a new `fix/<…>` / `feat/<…>` / `docs/<…>` / etc. name approved by the user).
+- The commit message follows the repo's existing conventional-commit style.
+- If `push` was provided, the branch is pushed upstream.
+- Every branch deemed unsafe in step 2 is left untouched in all cases.

.agents/skills/creating-issues/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: creating-issues
+description: >-
+  Turns a single feature idea, improvement, or bug into ONE well-structured GitHub issue. TRIGGER
+  when: the user wants to file/open/create an issue, turn a feature idea or improvement into a
+  ticket, or capture something missing or broken as a ticket. DO NOT TRIGGER when: breaking work
+  into multiple issues or planning a body of work → a planning skill; writing a full Product
+  Requirements Document → creating-prd; the idea is still fuzzy and unhardened → grilling-ideas
+  first.
+argument-hint: Feature, improvement, or bug to turn into a GitHub issue
+compatibility: Requires GitHub access (gh CLI authenticated, or an equivalent GitHub MCP/API tool) and write access to the target repository.
+metadata:
+  version: 0.1.0
+  author: OpsMill
+---
+
+# Create GitHub Issue
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+Treat `$ARGUMENTS` as the thing to file. If empty, ask the user what they want to capture before starting.
+
+## What this does
+
+Turn a feature idea, improvement, or bug into a single well-structured GitHub issue that matches the repository's own conventions. Keep it small and centred on **the need** — what is missing or broken, who it affects, and why it matters. **Do not propose a solution and do not write acceptance criteria for features** — leave the "how" to whoever picks the issue up. Always show the draft and get explicit approval before creating anything.
+
+## Core principle
+
+An issue states the need, not the answer. The person (or agent) who implements it decides the approach. For a feature or improvement that means no design, no task breakdown, no acceptance criteria — just a clear problem and its context. For a bug, the "need" is the misbehaviour itself, so reproduction details belong in the issue.
+
+## Workflow
+
+### 1. Learn the repository's conventions
+
+Probe whatever context the repo actually provides — don't assume a fixed layout:
+
+- [ ] Read context docs if present: `AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, `README`, or a `dev/` directory.
+- [ ] Check for issue templates in `.github/ISSUE_TEMPLATE/` and honour them if they exist.
+- [ ] List the repo's labels (`gh label list`) and a few recent issues (`gh issue list`) to match title style, labels, and tone.
+
+If the repo provides an issue template, honour its structure as-is — the fields are there deliberately. The only thing to hold back is *prescribing a solution*: fill the template's sections with the need and context, not with a design.
+
+### 2. Classify
+
+Decide whether this is a **feature / improvement** or a **bug**. When unsure, ask the user.
+
+### 3. Draft (need-focused)
+
+**Feature / improvement** — keep it lean:
+
+```markdown
+## Need
+
+[What's missing or could be better, who it affects, and why it matters now.]
+
+## Context
+
+[Only what's needed to understand the need: relevant area of the product, links to related discussion, constraints. No design.]
+
+## References
+
+- Related issue: #[number]
+- Documentation / discussion: [url]
+```
+
+**Bug** — capture the misbehaviour:
+
+```markdown
+## What happens
+
+[Observed behaviour.]
+
+## What should happen
+
+[Expected behaviour.]
+
+## Steps to reproduce
+
+1. ...
+2. ...
+
+## Environment
+
+[Version, OS, configuration, or other relevant context.]
+
+## References
+
+- Related issue: #[number]
+- Logs / screenshots: [link or `<details>` block]
+```
+
+Draft a clear, searchable title using the repo's convention (e.g. `feat:`, `fix:`, or whatever recent issues use), and pick labels from the repo's existing set.
+
+### 4. Get approval, then create
+
+**By default, present the full draft (title, labels, body) to the user and wait for explicit approval before creating the issue** — even when you have permission to create it directly. The gate exists to stop *silent* creation from mere permission; it is not meant to override a direct instruction.
+
+If the user has explicitly told you to file it without review (e.g. "just file it, don't ask"), honour that — but still echo the final title, labels, and body in your reply before (or as) you create it, so there's a record of what went out.
+
+Create the issue with the available tooling, for example:
+
+```bash
+gh issue create --title "[TITLE]" --body "[BODY]" --label "[LABELS]"
+```
+
+`--label` takes a comma-separated list (`--label 'bug,enhancement'`) — a space-separated value is treated as a single label name.
+
+Or the equivalent GitHub MCP call. Return the issue URL.
+
+## Quality gates
+
+Per `../quality-gates/gates/gate-model.md`. `creating-issues` is **Tier 0**; the existing
+user-approval step IS the independent judgment (R4) — no subagent is added.
+
+| Gate | Trigger | Tier | Primitives | Pass criteria | On-fail |
+|---|---|---|---|---|---|
+| Draft-shown | before `gh issue create` | T0 | P1 + human approval | The full draft is shown and the user approves. | revise per feedback |
+
+## Guardrails
+
+- Prefer clarity over completeness — a short, sharp issue beats a padded one.
+- Resist scope creep: one need per issue. If the input contains several, surface that and ask whether to split.
+- Don't invent labels, milestones, or assignees that don't exist in the repo.
+- Don't smuggle a solution into the "Need" or "Context" — if you catch yourself describing *how*, cut it.