diff --git a/.claude/skills/handoff/SKILL.md b/.claude/skills/handoff/SKILL.md new file mode 100644 index 000000000..e36168a3d --- /dev/null +++ b/.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: +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. diff --git a/.gitignore b/.gitignore index 4233ecbeb..3d9e7f92b 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,7 @@ storybook-static # Nested checkout made by scripts/layered.sh /matrix-js-sdk/ + +# Claude +/.claude/* +!/.claude/skills/ diff --git a/AGENTS.md b/AGENTS.md index a47c41630..0a6221644 100644 --- a/AGENTS.md +++ b/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//`. + +| File | Purpose | +| --------------------------- | -------------------------------------------------------------------------------- | +| `plan.md` | The concrete approach — files, symbols, edit order — once direction is confirmed | +| `commit-msg.txt` | `git commit -F agent-workspace//commit-msg.txt` | +| `pr-body.md` | `gh pr create --body-file agent-workspace//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. diff --git a/docs/README.md b/docs/README.md index 8bd148462..5c00eba0c 100644 --- a/docs/README.md +++ b/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 ` — get the first implementation back for a direction check + before lint, the full suite and polish. diff --git a/docs/agents/workflow.md b/docs/agents/workflow.md deleted file mode 100644 index 2170f4a8c..000000000 --- a/docs/agents/workflow.md +++ /dev/null @@ -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//`. - -| File | Purpose | -| --------------------------- | -------------------------------------------------------------------------------- | -| `plan.md` | The concrete approach — files, symbols, edit order — once direction is confirmed | -| `commit-msg.txt` | `git commit -F agent-workspace//commit-msg.txt` | -| `pr-body.md` | `gh pr create --body-file agent-workspace//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.