Adopt AGENTS.md as the canonical brief for AI coding tools

.claude/agents/story-writer.md

@@ -0,0 +1,42 @@
+---
+name: story-writer
+description: Drafts GitHub issues and user stories for this repo — terse, outcome-focused, and to the canonical shape. Use when asked to create, write, or file an issue/story.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You write GitHub issues and user stories for the Fallout VS Code extension repo.
+Your output is the issue body itself, not a conversation about it.
+
+**Before writing**, read `docs/issue-and-pr-style.md` — it is the binding style
+contract. Follow it exactly.
+
+Defaults:
+
+- Use the **Problem → Outcome → Acceptance criteria** shape. Drop any section
+  that doesn't apply rather than padding it.
+- Be terse. Lead with the point. No preamble, no restating the title, no
+  hedging, no marketing tone, no emoji headers. Match length to substance.
+- Prefer linking (`#123`, `src/model.ts:64`) over pasting.
+- Outcomes describe observable behaviour, not implementation.
+
+Scope check before you write: this repo is the **extension**, not the framework.
+Anything about target execution, the build engine, or how `build-graph.json` is
+*produced* belongs in [Fallout-build/Fallout](https://github.com/Fallout-build/Fallout).
+This repo owns how that graph is *displayed and driven* from VS Code. Say so
+rather than filing it in the wrong place.
+
+For bugs, the report is not actionable without three versions — VS Code,
+extension, and Fallout. The extension needs **Fallout 10.4.0+**; below that no
+`build-graph.json` is emitted at all, which accounts for most "empty view"
+reports. Rule that out before writing it up as an extension bug.
+
+When the request is underspecified, ask at most 1–2 sharp questions, then write.
+Do not invent acceptance criteria the user didn't imply — leave a `- [ ]` stub
+if unknown.
+
+If asked to file it, run `gh issue create` with `--title` and a `--body` that
+matches the shape. Apply exactly one category label — `enhancement` for stories
+unless told otherwise; the taxonomy is in `.github/release.yml`. This repo has
+no `target/YYYY` labels; that is a framework-repo convention. Report the created
+issue URL and nothing else.

.claude/commands/new-issue.md

@@ -0,0 +1,40 @@
+---
+description: Draft (and optionally file) a terse, outcome-focused GitHub issue to the repo's canonical shape.
+argument-hint: <one-line description of the problem/ask>
+allowed-tools: Read, Bash(gh issue create:*), Bash(gh label list:*)
+---
+
+Read `docs/issue-and-pr-style.md` and follow it as the binding style contract.
+Then draft a GitHub issue for: **$ARGUMENTS**
+
+Assemble the body to the canonical shape:
+
+```markdown
+### Problem
+<1–2 sentences>
+
+### Outcome
+<observable "done">
+
+### Acceptance criteria
+- [ ] <testable>
+- [ ] <testable>
+```
+
+Rules:
+
+- Terse. Lead with the point. No preamble, no restating the title, no filler.
+- Drop `Acceptance criteria` (and add a short `### Notes`) only if it doesn't
+  fit the ask. Don't invent criteria — leave `- [ ]` stubs if unknown.
+- Prefer links (`#123`, `src/model.ts:64`) over pasted blocks.
+- For a bug, include the three versions that make a report actionable here:
+  VS Code, extension, and Fallout. Most "the view is empty" reports are a
+  pre-10.4.0 framework emitting no `build-graph.json` at all — rule that out
+  before writing it up as an extension bug.
+
+Show me the drafted title and body first. **Do not file it until I confirm.**
+On confirmation, run `gh issue create --title "…" --body "…"` with exactly one
+category label (`enhancement`, `bug`, `breaking-change`, `security`,
+`documentation`, `dependencies`) — the taxonomy in `.github/release.yml`. This
+repo has no `target/YYYY` labels; that is a framework-repo convention. Report
+only the resulting issue URL.

.claude/skills/restructure-pr-commits/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: restructure-pr-commits
+description: "Restructure the commits on an existing PR into focused, reviewable commits"
+---
+
+Restructure the commits on PR `<number>` into focused, reviewable commits.
+Follow these steps in order exactly.
+
+## 0 — Check this is worth doing at all
+
+```
+gh pr view <number> --json baseRefName,title,url
+```
+
+**The base branch decides whether commit curation matters.** This repo enforces
+linear history with merge commits disabled, and the merge method differs by
+direction (`docs/branching-and-release.md#merging`):
+
+- **Base `main`** — merged with **rebase**. Every commit lands on the production
+  branch verbatim and becomes a permanent `git bisect` target. Curation matters;
+  proceed.
+- **Base `develop`** — merged with **squash**. The whole PR collapses to one
+  commit no matter how you arrange it. Restructuring is wasted effort — the
+  thing that actually needs care is the **PR title**, since that is what lands
+  on the trunk and what the release notes quote. Say so and stop, unless the
+  user explicitly wants the branch history tidied anyway.
+
+Use the real base ref from that command as `<base>` below — do not assume.
+
+## 1 — Find what the PR actually changes
+
+```
+git diff origin/<base> HEAD --stat
+```
+
+This is the authoritative list of files the PR modifies. `git log` is misleading
+on branches kept up to date via merge: merge commits drag base-branch history
+into the log as if it were authored on this branch — it isn't.
+
+## 2 — Find the branch's own commits
+
+```
+git log --first-parent --no-merges origin/<base>..HEAD --oneline
+```
+
+This shows only commits made directly on this branch.
+
+## 3 — Create a backup branch
+
+```
+git branch backup-pr-<number> HEAD
+```
+
+Do this before changing anything. Never skip this step.
+
+## 4 — Build the restructured history
+
+Check out a fresh branch from the base:
+```
+git checkout origin/<base> -b restructured-pr-<number>
+```
+
+Then restore the changed files from the backup:
+```
+git checkout backup-pr-<number> -- <files from step 1>
+```
+
+Handle renames explicitly: `git rm <old>` then `git checkout backup-pr-<number> -- <new>`.
+
+Commit in logical groups — one concern per commit. Commit message rules (from
+`docs/issue-and-pr-style.md`):
+- Functional imperative phrases; no conventional-commit prefixes (`fix:`, `feat:`, etc.)
+- Subject completes "This commit will…" without saying so
+- Body (when needed) explains *why*, not *what*; no file/class/type names
+
+Do not restructure across the generated/hand-written CI boundary: a change to
+`build/Build.CI.GitHubActions.cs` and the regenerated `.github/workflows/build.yml`
+belong in the **same** commit. Splitting them leaves a commit where the attribute
+and the workflow disagree, which is exactly the state the generated-file rule
+exists to prevent.
+
+## 5 — Verify file content is unchanged
+
+Run both and report the output:
+```
+git diff HEAD backup-pr-<number>
+git diff HEAD origin/<base> --stat
+```
+
+The first command must produce **no output**; if it does, stop and investigate before continuing.
+The second must list **exactly the same files** as step 1.
+
+## 6 — Stop and wait for explicit confirmation
+
+Show the new `git log --oneline` and ask the user to confirm the history looks
+correct. Do not proceed until the user explicitly says yes.
+
+## 7 — Push with --force-with-lease only after confirmation
+
+```
+git push origin HEAD:<pr-branch-name> --force-with-lease
+```
+
+Never use `--force` alone.
+
+## 8 — Update the PR title and description after confirmation
+
+Rewrite the PR title and description to match the restructured commits.
+Structure: Summary → one Changes section per commit → optional Combined effect.
+Each Changes section maps 1-to-1 to a commit. Keep the one category label
+correct — it is the changelog (`.github/release.yml`), and the title is the
+release-note line.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,111 @@
+name: 🐞 Bug Report
+description: "Report something that doesn't look alright."
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        _Hi there :wave: and thanks for taking the time to report a bug!_
+
+        _Before you continue, please check the [contribution guidelines](https://github.com/Fallout-build/Fallout.Extensions.VSCode/blob/develop/CONTRIBUTING.md)._
+
+  - type: markdown
+    attributes:
+      value: |
+        **Empty Targets view?** Check two things first — they account for most reports:
+        1. Your workspace builds with **Fallout 10.4.0 or later**. Earlier versions emit no build graph at all.
+        2. `.fallout/temp/build-graph.json` exists. Run `./build.ps1 --plan` once to generate it.
+
+  - type: input
+    id: usage-information
+    attributes:
+      label: Usage Information
+      description: Extension version / Fallout version / VS Code version / Operating System
+      placeholder: 10.4.30 / Fallout 10.4.0 / VS Code 1.96.2 / macOS 15.2
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Please share a clear and concise description of the problem.
+      placeholder: Description
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: Reproduction Steps
+      description: |
+        Minimal steps to reproduce. Include logs and exceptions as text rather than screenshots — except for genuinely visual problems (graph layout, tree icons, theme contrast), where a screenshot is the clearest evidence.
+      placeholder: Minimal Reproduction
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      placeholder: Expected Behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: If applicable, include error messages or stack traces.
+      placeholder: Actual Behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: build-graph
+    attributes:
+      label: Build graph
+      description: |
+        For anything about which targets appear, how they relate, or how the graph renders: paste the relevant slice of `.fallout/temp/build-graph.json`. Trim it to the targets involved — the whole file is rarely needed.
+      render: json
+    validations:
+      required: false
+
+  - type: textarea
+    id: extension-log
+    attributes:
+      label: Extension log
+      description: |
+        Optional. **Output** panel → select **Fallout** or **Log (Extension Host)** from the dropdown. Errors thrown during activation land there.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: regression
+    attributes:
+      label: Regression?
+      description: |
+        Did this work in a previous version of the extension? If you can try an earlier one, that helps narrow it down. If you don't know, that's OK.
+      placeholder: Regression?
+    validations:
+      required: false
+
+  - type: textarea
+    id: known-workarounds
+    attributes:
+      label: Known Workarounds
+      placeholder: Known Workarounds
+    validations:
+      required: false
+
+  - type: dropdown
+    id: pull-request
+    attributes:
+      label: Could you help with a pull-request?
+      description: See the [contribution guidelines](https://github.com/Fallout-build/Fallout.Extensions.VSCode/blob/develop/CONTRIBUTING.md).
+      options:
+        - "No"
+        - "Yes"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔒 Security vulnerability
+    url: https://github.com/Fallout-build/.github/blob/main/SECURITY.md
+    about: Don't file these as issues. Report privately via this repo's Security tab.
+  - name: 🧩 Fallout framework issues
+    url: https://github.com/Fallout-build/Fallout/issues
+    about: Build engine, targets, or how build-graph.json is produced — that's the framework, not this extension.
+  - name: 📚 Contributing & release docs
+    url: https://github.com/Fallout-build/Fallout.Extensions.VSCode/blob/develop/CONTRIBUTING.md
+    about: Branching, PR labels, and how this extension is built and released.
+  - name: 🧪 Preview build
+    url: https://github.com/Fallout-build/Fallout.Extensions.VSCode/releases/tag/preview
+    about: Every push to develop publishes a rolling pre-release .vsix. Worth checking your issue isn't already fixed there.

.github/ISSUE_TEMPLATE/feature_idea.yml

@@ -0,0 +1,53 @@
+name: 💡 Feature Idea
+description: "Suggest new features for the extension."
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        _Hi there :wave: and thanks for taking the time to send a feature idea!_
+
+        _Before you continue, please check the [contribution guidelines](https://github.com/Fallout-build/Fallout.Extensions.VSCode/blob/develop/CONTRIBUTING.md)._
+
+        _This repo is the **VS Code extension**. Ideas about targets, the build engine, or how the build graph is produced belong in the [framework repo](https://github.com/Fallout-build/Fallout/issues)._
+
+  - type: textarea
+    attributes:
+      label: Description
+      description: What should the new feature do?
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Usage Example
+      description: How would you use it — which view, command, or gesture?
+
+  - type: textarea
+    attributes:
+      label: Alternative
+      description: What do you do today instead?
+
+  - type: dropdown
+    id: needs-framework-change
+    attributes:
+      label: Does this need new data in build-graph.json?
+      description: |
+        If the extension would need information Fallout doesn't currently emit, this needs a framework change first and will be routed there. Pick "Not sure" if you don't know — that's fine.
+      options:
+        - "Not sure"
+        - "No — it works with what's already in the graph"
+        - "Yes — Fallout would need to emit something new"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: pull-request
+    attributes:
+      label: Could you help with a pull-request?
+      description: See the [contribution guidelines](https://github.com/Fallout-build/Fallout.Extensions.VSCode/blob/develop/CONTRIBUTING.md).
+      options:
+        - "No"
+        - "Yes"
+    validations:
+      required: true