Compact AGENTS.md and split hand-off out into a skill

.claude/skills/handoff/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: handoff
+description: Implement the first cut of a task and stop for a direction check before the quality pass.
+argument-hint: <the task>
+disable-model-invocation: true
+---
+
+Task: $ARGUMENTS
+
+Stop after the first implementation and hand it back before the quality pass.
+
+## Before the hand-off
+
+- Run the narrowest check that rules out an obviously broken hand-off: the test
+  file for the touched code, `tsc` on its own, a single story. Not the full
+  `pnpm lint`, not the whole suite.
+- If a wider check is needed before feedback can be useful, keep it to the touched
+  code and say why it was needed.
+- Leave wider refactors, extra tests and documentation polish out. They are
+  follow-up work, not part of the first hand-off.
+
+## The hand-off
+
+Stop and ask whether the direction is right. The message says:
+
+- what was built and where, in a few lines,
+- which check ran and what it returned, verbatim if it failed,
+- what was left out on purpose,
+- the decisions that could have gone another way.
+
+Do not continue past this point on your own.
+
+## After the user confirms
+
+The skill ends here. Continue with the quality pass as usual.

.gitignore

@@ -44,3 +44,7 @@ storybook-static
 
 # Nested checkout made by scripts/layered.sh
 /matrix-js-sdk/
+
+# Claude
+/.claude/*
+!/.claude/skills/

AGENTS.md

@@ -16,19 +16,35 @@ host's page. It is the MatrixRTC reference implementation.
   `@media`, global `i18next` or the `widget` global — take it from a provider.
 - The change works standalone, as a widget and as a component. Say what you checked.
 - Every gate below is green before you push.
-- Hand off after the first implementation, before the quality pass. Then commit on
-  the user's word where the setup allows it, or hand them the message.
 
 ## Read before you
 
 | …                                | …                                                          |
 | -------------------------------- | ---------------------------------------------------------- |
-| start a task of any size         | [docs/agents/workflow.md](docs/agents/workflow.md)         |
 | touch call logic or a view model | [docs/agents/architecture.md](docs/agents/architecture.md) |
 | write any code                   | [docs/agents/code-style.md](docs/agents/code-style.md)     |
 | write a test, story or e2e spec  | [docs/agents/testing.md](docs/agents/testing.md)           |
 | open a PR                        | [CONTRIBUTING.md](CONTRIBUTING.md)                         |
-| implement from a feature spec    | [FEATURES_SPEC/AGENTS.md](FEATURES_SPEC/AGENTS.md)         |
+
+## Scratch files live in `agent-workspace/`
+
+Git-ignored. One kebab-case subfolder per task, matching the branch topic:
+`agent-workspace/<slug>/`.
+
+| File                        | Purpose                                                                          |
+| --------------------------- | -------------------------------------------------------------------------------- |
+| `plan.md`                   | The concrete approach — files, symbols, edit order — once direction is confirmed |
+| `commit-msg.txt`            | `git commit -F agent-workspace/<slug>/commit-msg.txt`                            |
+| `pr-body.md`                | `gh pr create --body-file agent-workspace/<slug>/pr-body.md`                     |
+| `implementation-summary.md` | What was built, decisions, trade-offs                                            |
+| `NN-prompt.md`              | Raw prompt text, numbered, when worth keeping                                    |
+
+- Nothing here is durable. The folder is ignored, so anything worth keeping is
+  promoted into the PR body or a doc before the task ends.
+- Never write scratch files to the repo root. Stray `load_test_summary.md` and
+  `config.json_` files are what this folder prevents.
+- Start `pr-body.md` from `.github/PULL_REQUEST_TEMPLATE.md` and fill every
+  section.
 
 ## Gates
 
@@ -42,6 +58,11 @@ pnpm i18n:check
 `knip` fails on dead code; a file deliberately inert ahead of its consumer goes in
 `knip.ts` `ignoreFiles` with a reason.
 
+Ready means every gate is green and the change is covered at the layers
+[testing.md](docs/agents/testing.md) asks for. Read the diff against
+[code-style.md](docs/agents/code-style.md) first. Re-run the whole checklist after
+any fix.
+
 ## A good PR
 
 - One slice, under ~400 changed lines, green on its own, linked to its issue.

docs/README.md

@@ -14,7 +14,11 @@ This folder contains documentation for setup, usage, and development of Element
 
 Entry point: [AGENTS.md](../AGENTS.md).
 
-- [Agent workflow](./agents/workflow.md)
 - [Architecture](./agents/architecture.md)
 - [Code style](./agents/code-style.md)
 - [Testing](./agents/testing.md)
+
+Opt-in skills in [`.claude/skills/`](../.claude/skills/):
+
+- `/handoff <task>` — get the first implementation back for a direction check
+  before lint, the full suite and polish.

docs/agents/workflow.md

@@ -1,50 +0,0 @@
-# Agent workflow
-
-## Scratch files live in `agent-workspace/`
-
-Git-ignored. One kebab-case subfolder per task, matching the branch topic:
-`agent-workspace/<slug>/`.
-
-| File                        | Purpose                                                                          |
-| --------------------------- | -------------------------------------------------------------------------------- |
-| `plan.md`                   | The concrete approach — files, symbols, edit order — once direction is confirmed |
-| `commit-msg.txt`            | `git commit -F agent-workspace/<slug>/commit-msg.txt`                            |
-| `pr-body.md`                | `gh pr create --body-file agent-workspace/<slug>/pr-body.md`                     |
-| `implementation-summary.md` | What was built, decisions, trade-offs                                            |
-| `NN-prompt.md`              | Raw prompt text, numbered, when worth keeping                                    |
-
-- Nothing here is durable. The folder is ignored, so anything worth keeping is
-  promoted into the PR body, a doc, or a feature spec before the task ends.
-- Never write scratch files to the repo root. Stray `load_test_summary.md` and
-  `config.json_` files are what this folder prevents.
-- Start `pr-body.md` from `.github/PULL_REQUEST_TEMPLATE.md` and fill every
-  section.
-- Commit subjects are plain imperative English. No conventional-commits prefixes.
-- A `plan.md` and a feature spec sit at different altitudes; neither replaces the
-  other. A spec in `FEATURES_SPEC/` is durable and deliberately abstract —
-  behaviour, decisions, acceptance criteria — so the feature can be rebuilt against
-  a `main` nobody has seen yet. A plan is one slice of it landing on today's
-  `main`: the paths, symbols and edit order the spec's decisions and criteria must
-  not name. `FEATURES_SPEC/AGENTS.md` wins wherever the two genuinely overlap.
-
-## Hand off before the quality pass
-
-- Implement the change, run the narrowest check that rules out an obviously broken
-  handoff, then stop and ask whether the direction is right.
-- Full `pnpm lint`, the whole suite, coverage and benchmarks come after the
-  direction is confirmed.
-- Wider refactors, extra tests and documentation polish are follow-up work, not
-  part of the first handoff.
-- If a check is needed before feedback, keep it to the touched code and say why.
-
-## Commit and PR readiness
-
-- Commit once the user confirms direction, or asks for one. Not before. Where the
-  setup has no git identity, a sandbox included, write the message to
-  `commit-msg.txt` and hand it over instead.
-- Ready means every gate in [AGENTS.md](../../AGENTS.md#gates) is green and the
-  change is covered at the layers [testing.md](./testing.md) asks for. Read the diff
-  against [code-style.md](./code-style.md) first.
-- Re-run the whole checklist after any fix. Only on green, either way.
-- Once a human has started reviewing, fix forward — never force-push a
-  regeneration over a review in progress.