feat: multi-agent commands & skill discovery (phase 2b, v0.17.0)

.context/CONTEXT.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**dotcontext** is an AI context toolkit for Claude Code. It provides commands, decisions, skills, and feature planning workflows that help AI assistants understand and work with your codebase.
+**dotcontext** is an AI context toolkit for coding agents — Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, and Cursor. It provides commands, decisions, skills, and feature planning workflows that help AI assistants understand and work with your codebase.
 
 **Users:** Developers and teams who use AI coding assistants and want to provide them with project context.
 
@@ -14,12 +14,13 @@
 
 | Entity | Responsibility |
 |--------|----------------|
-| `CLAUDE.md` | Root-level project context: stack, commands, critical rules, architecture overview |
+| `AGENTS.md` | **Canonical** root-level project instructions: stack, commands, critical rules, architecture, workflows. Read natively by Codex/opencode/Copilot/Cursor |
+| `CLAUDE.md` / `GEMINI.md` | Thin `@AGENTS.md` import stubs for Claude Code / Gemini CLI (emitted per selected harness) |
 | `.context/CONTEXT.md` | Domain knowledge: entities, flows, integrations, glossary |
 | `ADR (Architectural Decision Record)` | Documents a significant architectural decision with context, alternatives, and consequences |
 | `Skill` | Step-by-step guide for a recurring pattern or task in the codebase |
 | `PRP (Product Requirements Prompt)` | Structured feature specification with implementation plan and phases |
-| `Command` | Custom Claude Code slash command (markdown file in `.claude/commands/`) |
+| `Command` | A workflow prompt, emitted per harness (`.claude/commands/`, `.opencode/command/`, `.github/prompts/`, or the `## Workflows` section of `AGENTS.md`) |
 | `Discovery` | Output document from deep context analysis with business rules and cross-repo validation |
 | `Bug Report` | Structured report from `/fix-bug` with root cause, reproduction test, and fix details |
 

.context/decisions/003-safe-update-behavior.md

@@ -43,19 +43,19 @@ There is **no `--force` flag** — it was removed (it had degenerated into a pla
 ## Consequences
 
 ### Positive
-- User customizations are preserved by default
-- Explicit `--force` prevents accidental data loss
-- Simple mental model: default is safe
+- User customizations (seeds) are preserved by default — never force-overwritten
+- Managed files stay current via a diff-and-prompt update (no blunt overwrite needed)
+- Simple mental model: seeds are create-only, managed files prompt
 - New templates from updates are still available
 
 ### Negative
-- Users with outdated templates may not get improvements
-- Must document that `--force` is needed for full reset
-- No way to selectively update one template
+- Users with outdated seed files may not get improvements (by design — seeds are user-owned)
+- To reset a seed, the user must delete it and re-run update
+- No destructive `--force` flag (removed in v2.0); `--yes` only auto-confirms managed updates
 
 ### Risks
 - Users may not realize their templates are outdated
-- Mitigation: Add `dotcontext status` command to check for template drift (future)
+- Mitigation: `dotcontext doctor` reports when a newer version is available (ADR-015)
 
 ## History
 

.context/decisions/004-claude-code-integration.md

@@ -1,10 +1,15 @@
 # ADR-004: Claude Code Integration via Slash Commands
 
-**Status:** Accepted
+**Status:** Accepted (extended beyond Claude by ADR-016/017/018)
 **Date:** 2025-01-31
 **Version:** 1.0
 **Deciders:** Gocase Team
 
+> **Note (2026-06):** the "tightly coupled to Claude Code (won't work with other AI tools)" tradeoff below
+> has been lifted — dotcontext now serves six harnesses. Instructions go through a canonical `AGENTS.md`
+> (ADR-016), skills/hooks port per agent (ADR-017), and workflows reach each agent's command primitive or
+> the `AGENTS.md` Workflows section (ADR-018). This ADR is kept as the original Claude-first record.
+
 ## Context
 
 dotcontext creates documentation structure, but the real value comes from AI assistants using that documentation. We needed to decide how to integrate with Claude Code (Anthropic's CLI for Claude).
@@ -52,3 +57,6 @@ Commands created:
 
 ## Related
 - ADR-005: AskUserQuestion requirement
+- ADR-016: Multi-agent harness (extends this beyond Claude)
+- ADR-017: Skills & hooks portability + harness selection
+- ADR-018: Command portability & invocation modes

.context/decisions/005-askuserquestion-requirement.md

@@ -63,6 +63,12 @@ The root `CLAUDE.md` also includes this as Critical Rule #1:
 | 1.0 | 2025-02-02 | Initial decision |
 | 2.0 | 2026-05-21 | Replaced fixed "10 questions" quota in `/generate-prp` with clarity-assessment policy (0..N questions). Selectively absorbed ideas from spec-driven-build skill without adopting its full ceremony. |
 
+> **Cross-agent note (2026-06):** `AskUserQuestion` is Claude's tool name. Every supported agent ships an
+> equivalent structured-question tool (`request_user_input`, `question`, `ask_user`, `cursor/ask_question`),
+> so this requirement holds on all of them. ADR-018 makes it portable via a neutral `{{ASK}}` convention
+> that renders to each agent's native tool — it does not degrade to free text.
+
 ## Related
 - ADR-004: Claude Code integration
 - ADR-011: Test-Driven Bug Fixing Pattern (partial exception — `/fix-bug` skips initial questions)
+- ADR-018: Command portability — generalizes this requirement across agents via `{{ASK}}`

.context/decisions/014-automated-release-pipeline.md

@@ -28,7 +28,8 @@ Inspired by github/spec-kit's tag-triggered release workflow, which generates no
    `v*` tag. The workflow:
    - runs `make build` and fails if the committed `dotcontext` is out of sync with `src/`,
    - fails if the tag does not match the binary's `VERSION`,
-   - generates release notes from `git log --no-merges` since the previous tag,
+   - takes release notes from the matching `CHANGELOG.md` section (falling back to `git log --no-merges`
+     since the previous tag when no section exists), since squash-merges make the git log too sparse,
    - runs `gh release create`. Humans must not call `gh release create` by hand.
 
 3. **A CI workflow (`.github/workflows/ci.yml`)** runs on PRs and pushes to `main`:
@@ -44,8 +45,8 @@ Inspired by github/spec-kit's tag-triggered release workflow, which generates no
 
 ### Negative
 - Contributors must remember to `make build` and commit the binary (now enforced by CI).
-- Release notes from `git log` are only as good as commit hygiene; the curated `CHANGELOG.md`
-  entry remains the human-readable record.
+- Release notes are only as good as the `CHANGELOG.md` entry for that version, so each release needs a
+  written changelog section (the `git log` fallback is sparse under squash-merge).
 
 ## Alternatives Considered
 

.context/decisions/015-capability-discovery-and-update-awareness.md

@@ -13,7 +13,7 @@ Two gaps surfaced while comparing dotcontext to github/spec-kit:
    ran `dotcontext update`. spec-kit's `specify self check` surfaces "update available" passively.
 2. **No machine-readable capability handshake.** spec-kit exposes `specify version --features --json`
    so a harness can discover what the tool supports before invoking it. This becomes important for
-   the planned multi-agent work (ADR-016, forthcoming), where a harness must know whether features
+   the multi-agent work (ADR-016), where a harness must know whether features
    like `AskUserQuestion`, statusline, or multi-agent output are available.
 
 A standing project constraint is to keep the CLI surface minimal — new flows belong inside existing
@@ -29,8 +29,9 @@ commands, not as new top-level subcommands (see ADR-007).
 
 2. **`--version` gains `--features` and `--json`.** Plain `--version` is unchanged. `--features` prints
    a human-readable capability list; `--json` emits a machine-readable handshake (name, version, repo,
-   commands, and a `capabilities` object) with **no jq dependency** (hand-built JSON). The current
-   `capabilities.multiagent` is `false` and `agents` is `["claude"]`; these flip when ADR-016 lands.
+   commands, and a `capabilities` object) with **no jq dependency** (hand-built JSON). Since ADR-016/017/018
+   landed, `capabilities.multiagent` is `true`, `skills`/`hooks`/`commands` are `true`, and `agents` lists
+   the full adapter registry (`claude codex opencode gemini copilot cursor`).
 
 ## Consequences
 
@@ -59,4 +60,4 @@ commands, not as new top-level subcommands (see ADR-007).
 ## Related
 - ADR-007: CLI simplification
 - ADR-005: Mandatory AskUserQuestion (a capability that does not port to other agents)
-- ADR-016: Multi-agent harness support (forthcoming) — will consume the capability handshake
+- ADR-016: Multi-agent harness support — consumes the capability handshake

.context/decisions/016-multi-agent-harness.md

@@ -106,6 +106,7 @@ This ADR covers the **instructions file** only. Skills and hooks portability is
 
 ## Related
 - ADR-004: Claude Code integration (this extends it beyond Claude)
-- ADR-005: Mandatory AskUserQuestion (will get a v2.0 for command portability in phase 2b)
-- ADR-007: CLI simplification (interactive detection, no new flags)
+- ADR-005: Mandatory AskUserQuestion (ADR-018 renders `{{ASK}}` to each agent's native question tool)
+- ADR-007: CLI simplification (interactive detection; the `--agents` flag is a scoped exception, see ADR-017)
 - ADR-015: Capability discovery & update awareness (the handshake this populates)
+- ADR-017 / ADR-018: skills & hooks portability, command portability

.context/decisions/018-command-portability-and-invocation-modes.md

@@ -1,7 +1,8 @@
 # ADR-018: Command Portability & Invocation Modes (phase 2b plan)
 
-**Status:** Proposed
+**Status:** Accepted
 **Date:** 2026-06-03
+**Version:** 1.0
 **Deciders:** Nicholas (Gocase)
 
 ## Context
@@ -39,19 +40,41 @@ Rationale for the promotions: `code-review` and `deep-context` are read-mostly,
 / "help me understand X" are natural auto-triggers — discovery adds value with no side-effect risk, and
 the explicit `/name` still works.
 
-### 2. Emit per agent by mode
+### 2. Emit per agent by mode — **hybrid** (chosen)
 
 - `skill` mode → `SKILL.md` (already ports to all six — ADR-017).
-- `command` mode → each agent's **explicit** primitive: Claude command, opencode command, Copilot
-  prompt file, Gemini custom command (TOML), Cursor skill + `disable-model-invocation`, Codex prompt
-  (global `~/.codex/prompts/`, namespaced). Where an agent only offers auto-skills, use its explicit
-  flag if honored, otherwise fall back to documenting the workflow in `AGENTS.md`.
+- `command` mode → **native command/prompt files where the format is markdown-compatible and safe**,
+  and **`AGENTS.md` documentation everywhere else**:
+  - **Claude** → `.claude/commands/<name>.md` (slash command)
+  - **opencode** → `.opencode/command/<name>.md`
+  - **Copilot** → `.github/prompts/<name>.prompt.md`
+  - **Gemini, Cursor, Codex** → a **`## Workflows`** section in `AGENTS.md` (lists each workflow + when
+    to use). Rejected per-agent transforms (Gemini TOML, Cursor skill+flag, Codex global prompts) as
+    high-effort, format-divergent, and not runtime-verifiable here — the `AGENTS.md` section makes the
+    workflows usable on those agents without fragile generation.
+
+The canonical bodies are the existing `templates/.claude/commands/*.md`; opencode/Copilot receive copies
+(create-only). The `AGENTS.md` Workflows section also instructs every agent to use its **native
+structured-question tool** for clarification.
+
+> **Note:** the `code-review`/`deep-context` skill-mode promotion (item 1) is recorded but **not yet
+> applied** — they currently ship as commands. Converting them to discoverable `SKILL.md` is a small
+> follow-up within phase 2b.
 
 ### 3. Portable `{{ASK}}` directive
 
 Command/skill bodies express requirement-gathering with a portable `{{ASK: question | optA | optB }}`
-directive. At emit time it renders to each agent's **native** structured-question tool — it does **not**
-degrade to free text. This satisfies ADR-005's clarity-assessed questioning on every agent.
+directive. Because **every** agent ships a native structured-question tool (Context fact 2), this is an
+**authoring convention**, not a runtime transformer: bodies say "ask the user via your structured-question
+tool: …", and each agent's model uses its own (`AskUserQuestion` / `ask_user` / `question` / …). It does
+**not** degrade to free text, and satisfies ADR-005's clarity-assessed questioning on every agent.
+
+### 4. Skill frontmatter (`name` + `description`) — DONE
+
+Every `SKILL.md` now opens with YAML frontmatter (`name` matching the directory, a keyword-front-loaded
+`description`). Without it the model can't auto-discover a skill — only explicit `/name` works — which
+would defeat the description-driven discovery ADR-016/017 rely on. Applied to all four current skills
+(`bug-reproduction`, `batch-operations`, `git-platform`, `update-api-documentation`).
 
 ## Consequences
 
@@ -71,7 +94,7 @@ degrade to free text. This satisfies ADR-005's clarity-assessed questioning on e
 
 | Version | Date | Changes |
 |---------|------|---------|
-| 1.0 (proposed) | 2026-06-03 | Initial plan for phase 2b |
+| 1.0 | 2026-06-03 | Accepted — skill frontmatter + hybrid command portability (opencode/Copilot native; AGENTS.md Workflows for Gemini/Cursor/Codex) |
 
 ## Related
 - ADR-005: Mandatory AskUserQuestion (clarity assessment) — `{{ASK}}` is how it's satisfied cross-agent

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: "[bug] "
+labels: bug
+---
+
+**What you ran** (the exact `dotcontext` command, and which agent/harness — Claude, Codex, opencode, Gemini, Copilot, Cursor):
+
+```
+```
+
+**`dotcontext --version`:**
+
+**OS / shell:**
+
+**Expected:**
+
+**Actual** (paste the output):
+
+```
+```
+
+**Steps to reproduce:**
+1.
+2.
+
+**`dotcontext doctor` output** (optional, often helpful):
+
+```
+```

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: How to contribute (add a skill, etc.)
+    url: https://github.com/goca-se/dotcontext/blob/main/CONTRIBUTING.md
+    about: Read the contributing guide before opening a PR.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea — a new skill, harness, command, or improvement
+title: "[feat] "
+labels: enhancement
+---
+
+**Use case** — what are you trying to do, and why? ("I'm trying to … so that …")
+
+**Proposed solution:**
+
+**If this is a new skill or harness, which agent(s) does it target?**
+(Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, Cursor)
+
+**Alternatives considered:**
+
+**Additional context:**

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!-- Thanks for contributing! Keep the summary tight. See CONTRIBUTING.md. -->
+
+## Summary
+
+<!-- What does this change and why? -->
+
+## Changes
+
+-
+
+## Type
+
+- [ ] Skill / template (no `src/` change)
+- [ ] CLI behavior (`src/` change — rebuilt the `dotcontext` binary)
+- [ ] Docs / ADR
+- [ ] Other
+
+## Checklist
+
+- [ ] Ran `make build` and committed the rebuilt `dotcontext` (CI fails if it's out of sync with `src/`)
+- [ ] `bash -n` passes and I tested locally (`./dotcontext …`)
+- [ ] New skills include `name`/`description` frontmatter and are wired into `init.sh` + `update.sh`
+- [ ] Checked `.context/decisions/` — no ADR conflict (or I noted/added one)
+- [ ] Conventional-commit style on commits (`feat:` / `fix:` / `docs:` / `chore:`)
+
+## Test plan
+
+-

.github/workflows/release.yml

@@ -1,7 +1,8 @@
 name: Release
 
 # Tag-triggered release: push a vX.Y.Z tag and this builds, verifies, and
-# publishes a GitHub release with notes generated from the git log.
+# publishes a GitHub release. Notes come from the matching CHANGELOG.md section
+# (falling back to the git log when no section exists).
 on:
   push:
     tags:
@@ -39,16 +40,33 @@ jobs:
 
       - name: Generate release notes
         run: |
+          ver="${GITHUB_REF_NAME#v}"
           prev="$(git describe --tags --abbrev=0 "${GITHUB_REF_NAME}^" 2>/dev/null || echo "")"
+
+          # Prefer the curated CHANGELOG.md section for this version (everything
+          # between its "## [ver]" header and the next "## [" header).
+          notes="$(awk -v ver="$ver" '
+            index($0, "## [" ver "]") == 1 { capture=1; next }
+            capture && index($0, "## [") == 1 { exit }
+            capture { print }
+          ' CHANGELOG.md)"
+
           {
-            echo "## What's Changed"
-            echo ""
+            if [ -n "$(printf '%s' "$notes" | tr -d '[:space:]')" ]; then
+              printf '%s\n' "$notes"
+            else
+              # Fallback: build from the git log since the previous tag.
+              echo "## What's Changed"
+              echo ""
+              if [ -n "$prev" ]; then
+                git log --no-merges --pretty='* %s (%h)' "${prev}..${GITHUB_REF_NAME}"
+              else
+                git log --no-merges --pretty='* %s (%h)' "${GITHUB_REF_NAME}"
+              fi
+            fi
             if [ -n "$prev" ]; then
-              git log --no-merges --pretty='* %s (%h)' "${prev}..${GITHUB_REF_NAME}"
               echo ""
               echo "**Full Changelog**: https://github.com/${GITHUB_REPOSITORY}/compare/${prev}...${GITHUB_REF_NAME}"
-            else
-              git log --no-merges --pretty='* %s (%h)' "${GITHUB_REF_NAME}"
             fi
           } > RELEASE_NOTES.md
           cat RELEASE_NOTES.md