@ethlete/agent-rules 0.1.0-next.4 → 0.1.0-next.6

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.6
+
+### Minor Changes
+
+- [#3055](https://github.com/ethlete-io/ethdk/pull/3055) [`86cd6e9`](https://github.com/ethlete-io/ethdk/commit/86cd6e97072d38436650ddc94a15527da34fa946) Thanks [@github-actions](https://github.com/apps/github-actions)! - Add the git-flow branch convention: a `git-flow` skill, `ethlete-agents git-flow start|check|repair|explain`, opt-in git hooks, and the parser at `@ethlete/agent-rules/git-flow`.
+
+### Patch Changes
+
+- [#3055](https://github.com/ethlete-io/ethdk/pull/3055) [`01b0797`](https://github.com/ethlete-io/ethdk/commit/01b0797d80df17e740419402034bc3eec739daaf) Thanks [@github-actions](https://github.com/apps/github-actions)! - The context-warning hook now points at `/ethlete-handoff`, the name the generated skill actually has, instead of a `/handoff` command that does not exist in a consumer repo.
+
+## 0.1.0-next.5
+
+### Minor Changes
+
+- [#3048](https://github.com/ethlete-io/ethdk/pull/3048) [`6e19999`](https://github.com/ethlete-io/ethdk/commit/6e199997f51b88aaa1860a56a6b96be057ba1205) Thanks [@github-actions](https://github.com/apps/github-actions)! - The `context-warning` hook now runs under Codex as well as Claude Code, registered in
+  `.codex/hooks.json` whenever the `codex` target is on.
+
+- [#3049](https://github.com/ethlete-io/ethdk/pull/3049) [`a606dda`](https://github.com/ethlete-io/ethdk/commit/a606dda0695ac8cc4370816bf3ff1c0814436091) Thanks [@TomTomB](https://github.com/TomTomB)! - Add the `figma-export` skill, guiding agents through reconciling a component against a Figma "copy as CSS" export.
+
+### Patch Changes
+
+- [#3048](https://github.com/ethlete-io/ethdk/pull/3048) [`fc56189`](https://github.com/ethlete-io/ethdk/commit/fc56189450a45f2b5819d40945a71205a6d67ba0) Thanks [@github-actions](https://github.com/apps/github-actions)! - The `query` skill now says to prefer `withArgs` over passing `args` to `execute()`, and when the imperative form is still right.
+
+- [#3048](https://github.com/ethlete-io/ethdk/pull/3048) [`a16cc69`](https://github.com/ethlete-io/ethdk/commit/a16cc698a3cd3f14d0419d8f9710929fb41b4711) Thanks [@github-actions](https://github.com/apps/github-actions)! - Figma export skill: read an SVG frame as well as the CSS dump, with a `dump-figma-svg.py`
+  that prints its box tree and measures the auto-layout gaps.
+
 ## 0.1.0-next.4
 
 ### Minor Changes

package/README.md

@@ -113,10 +113,122 @@ Prettier rewrites them and `check` then reports drift on every run:
 Content that declares `requires` is only emitted when those packages are installed, so
 a repo without `@ethlete/query` never sees the query guide.
 
+## Git flow
+
+The branch convention lives in the same config, as one machine-readable grammar that the
+CLI, a git hook, a CI job and `@ethlete/timetrack` all read:
+
+```json
+{
+  "gitFlow": {
+    "keyPrefixes": ["FIP"],
+    "baseBranches": { "development": "next", "production": "main" }
+  }
+}
+```
+
+```bash
+npx ethlete-agents git-flow start FIP-2177          # name it and branch off the right base
+npx ethlete-agents git-flow check                   # the current branch
+npx ethlete-agents git-flow check "$SOURCE" --target "$TARGET"
+npx ethlete-agents git-flow check --all             # adoption report
+npx ethlete-agents git-flow repair dev-game-codes --key FIP-2900
+npx ethlete-agents git-flow explain feat/FIP-2177-user-management
+```
+
+The shapes:
+
+| Shape                                      | Branch from             | Merges into                    |
+| ------------------------------------------ | ----------------------- | ------------------------------ |
+| `feat/<KEY>-<subject>`                     | development             | development                    |
+| `sub/feat/<KEY>-<subject>/<KEY>-<subject>` | the main feature branch | the main feature branch        |
+| `release/<YYYY.MM.DD>`                     | development             | development **and** production |
+| `sub/release/<YYYY.MM.DD>/<KEY>-<subject>` | the release branch      | the release branch             |
+| `hotfix/<KEY>-<subject>`                   | production              | production                     |
+
+**Why nested branches carry a `sub/` prefix.** Git refuses a ref that is both a branch and
+a directory of branches, so `feat/FIP-2177-user-management/FIP-2178-reset` cannot exist
+while `feat/FIP-2177-user-management` does - the push is rejected with `refname conflict`.
+The prefix moves the nested tree out of the way while keeping the parent's full path inside
+the child's name, so the merge request target is still derivable from the name alone. The
+unprefixed spelling still parses, reports why it cannot exist, and `repair` moves it.
+Configurable as `subPrefix`.
+
+- **`enforcement`** - `"advisory"` (default) reports everything and blocks nothing, so a
+  repo can adopt the convention before it gates on it. `"gated"` applies each rule's
+  `severity`. A direct push to a base branch is blocked in both modes, and
+  `wrong-mr-target` can be raised to `"error"` on its own without ending the naming
+  grace period.
+- **`keyPrefixes`** - the project's issue prefixes. Leave it empty and anything shaped
+  like `keyPattern` counts, which reads `chore/angular-22` as issue `ANGULAR-22`.
+- **`severity`** - per rule: `unknown-type`, `missing-key`, `key-case`,
+  `missing-subject`, `type-alias`, `deprecated-prefix`, `release-date`,
+  `wrong-mr-target`, `protected-push`.
+- **`deprecatedShapes`** - legacy spellings that still classify correctly and only earn a
+  rename suggestion. `dev-*` ships as the old spelling of a main feature branch.
+
+The grammar is also importable on its own - `@ethlete/agent-rules/git-flow` has no
+dependencies and touches no Node built-ins, so it runs in a browser:
+
+```ts
+import { parseBranch, planStart, resolveGitFlowConfig } from '@ethlete/agent-rules/git-flow';
+
+const { storyKey, taskKey, findings } = parseBranch({ branch, config: resolveGitFlowConfig() });
+```
+
+### `start` - the prospective flow
+
+`git-flow start <KEY>` reads the issue from Jira, computes the name from the grammar and
+creates the branch off the correct base. It prints the plan first and asks before writing;
+`--dry-run` stops after the plan and `--yes` skips the question. It refuses on a dirty
+working tree, when the branch already exists, and when the base branch is nowhere to be
+found.
+
+A Task with a parent Story nests under that Story's feature branch, which therefore has to
+exist already - `start` says so rather than inventing a parent. `--of <branch>` picks the
+parent explicitly, `--hotfix` branches off production, `--release <date>` makes a release
+branch, and `--subject <text>` skips Jira entirely.
+
+Jira needs a host, an email and an API token. Only the host belongs in the committed
+config; the two secrets come from `JIRA_EMAIL` / `JIRA_API_TOKEN` or from the gitignored
+local config.
+
+```json
+{
+  "jira": {
+    "host": "https://your-team.atlassian.net",
+    "subjectField": "customfield_10050",
+    "typeByIssueType": { "Bug": "fix" }
+  }
+}
+```
+
+- **`subjectField`** - the field holding a Story's branch subject. Without it the summary
+  is slugified, which is a paraphrase rather than the agreed subject.
+- **`typeByIssueType`** - the branch type per Jira issue type; anything unlisted becomes
+  `feat`. `--type` overrides it per call.
+
+### `repair` - renaming a branch that does not conform
+
+`git-flow repair [ref]` derives the conforming name (`--key FIP-2900` when the old name
+carries no issue key, `--to <branch>` to override), renames the branch locally and on the
+remote, and retargets the open merge requests aimed at it through the GitLab API.
+`GITLAB_TOKEN` needs the `api` scope.
+
+Everything is checked before the first mutation, and it refuses rather than half-finishing:
+
+- An open merge request whose **source** is the branch blocks the repair. GitLab cannot
+  move a merge request to another source branch, and closing it would lose its discussion -
+  merge or close it first.
+- A branch that is pushed but whose merge requests cannot be listed (no token, or a remote
+  that is not GitLab) blocks too. `--no-mr-check` asserts that none point at it.
+- If a retarget fails halfway, the old branch is still there and the recovery commands are
+  printed.
+
 ## Hooks (opt-in)
 
-Claude Code hooks run commands on the developer's machine, so none are emitted by
-default - opt in per hook in the config:
+Hooks run commands on the developer's machine, so none are emitted by default - opt in
+per hook in the config:
 
 ```json
 {
@@ -124,20 +236,82 @@ default - opt in per hook in the config:
 }
 ```
 
-`sync` writes the script to `.claude/hooks/ethlete/` and registers it in
-`.claude/settings.json` (your own entries are left untouched); removing the name from
-`hooks` unregisters and deletes it again.
+They are emitted for whichever of the `claude` and `codex` targets is enabled:
+
+| Target   | Script                   | Registered in           |
+| -------- | ------------------------ | ----------------------- |
+| `claude` | `.claude/hooks/ethlete/` | `.claude/settings.json` |
+| `codex`  | `.codex/hooks/ethlete/`  | `.codex/hooks.json`     |
+
+Your own entries in those files are left untouched; removing the name from `hooks`
+unregisters and deletes the script again. Codex only loads project-local hooks once the
+`.codex/` layer is trusted, and honours `[features] hooks = false`.
 
 Available hooks:
 
-- **`context-warning`** - warns once per tier (and instructs Claude) when the session
-  context crosses 70% / 85% of the token budget, recommending `/handoff`. The budget is
-  capped at the 200k long-context pricing boundary: on 1M-window models every request
-  past 200k input tokens bills the whole context at a premium rate, so the warnings
-  fire at ~140k/~170k instead of deep into the expensive range.
+- **`context-warning`** - warns once per tier (and instructs the agent) when the session
+  context crosses 70% / 85% of the token budget, recommending a handoff. Under Claude the
+  budget is capped at the 200k long-context pricing boundary: on 1M-window models every
+  request past 200k input tokens bills the whole context at a premium rate, so the
+  warnings fire at ~140k/~170k instead of deep into the expensive range. Codex has no
+  such boundary, so its budget is the model's own reported context window and the
+  warnings are pure occupancy.
+
+  Two things are Claude-only: the separate user-facing line (Codex documents only
+  `additionalContext`, so there the warning is folded into the text the model is told to
+  relay), and the auto-mode escalation that writes the handoff file unprompted - Codex's
+  `permission_mode` values are undocumented, so no value enables it.
 
 Hooks can be turned off per machine - see the local config below.
 
+## Git hooks (opt-in)
+
+Separate from the agent hooks above, and opt-in for the same reason - a generated block
+that can reject a push is a higher-stakes artifact than a markdown one:
+
+```json
+{
+  "gitHooks": ["pre-push", "post-checkout"]
+}
+```
+
+Each one is written as an `# ethlete:git-flow:start` … `end` block **appended** to your
+`.husky/<name>`, so an existing hook there (a git-lfs hook, typically) keeps working and
+keeps reading stdin first - which is why the block never reads stdin itself. Removing the
+name from `gitHooks` takes the block back out and leaves the rest of the file alone.
+
+- **`pre-push`** - runs `git-flow check --push` on the current branch. In `advisory` mode
+  only a direct push to a base branch can actually stop it.
+- **`post-checkout`** - reports a non-conforming name on a branch that is on no remote yet,
+  which is the whole window in which renaming it is free.
+
+Only `.husky/` is written, never `.git/hooks/`: the generated files are committed and CI's
+`check` diffs them, so a hook outside the working tree could never be in sync. Without a
+`.husky/` directory `sync` warns and writes nothing. The block calls
+`node_modules/.bin/ethlete-agents` directly rather than through `npx`, so a repo where the
+package is missing gets silence instead of a registry lookup that would fail the push.
+`ETHLETE_GIT_FLOW_SKIP=1` silences both hooks on one machine.
+
+## CI job
+
+On GitLab, the merge request target is the half no local hook can see. The job needs no
+configuration beyond the predefined variables:
+
+```yaml
+Git Flow:
+  stage: Checks
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  allow_failure: true
+  script:
+    - >
+      npx ethlete-agents git-flow check "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
+      --target "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+```
+
+`allow_failure: true` on top of `advisory` mode is deliberate belt and braces: the job
+reports for a whole grace period before it can ever be the reason a merge request is red.
+
 ## Per-machine local config
 
 A gitignored `ethlete-agents.config.local.json` at the repo root holds the values that
@@ -146,13 +320,20 @@ differ per developer, without touching any committed file:
 ```json
 {
   "disableHooks": true,
-  "sdkSourcePath": "/absolute/path/to/ethlete-sdk"
+  "sdkSourcePath": "/absolute/path/to/ethlete-sdk",
+  "jira": { "email": "you@example.com", "token": "…" }
 }
 ```
 
 - **`disableHooks`** - `true` disables every generated hook; an array
   (`["context-warning"]`) just the named ones. The hook scripts read the file at
   runtime, so toggling takes effect on the next prompt - no `sync` needed.
+- **`disableAutoHandoffSave`** - keeps the `context-warning` hook's tiered warnings but
+  drops the auto-mode escalation: at the critical tier it recommends `/ethlete-handoff`
+  instead of saving the handoff file itself.
+- **`jira`** - the credentials `git-flow start` needs (`host`, `email`, `token`). This is
+  the one place in a repo a secret may sit, and only because the file is gitignored;
+  `JIRA_EMAIL` / `JIRA_API_TOKEN` in the environment are the alternative and win over it.
 - **`sdkSourcePath`** - a local `ethlete-sdk` checkout. The `sdk-source` and
   `sdk-local-build` skills read it when the agent needs the SDK's own sources, or has to
   build the SDK and install it here through a `file:` dependency. A relative path is

package/content/git-hooks/post-checkout.sh

@@ -0,0 +1,10 @@
+if [ "$3" = "1" ] && [ -z "$ETHLETE_GIT_FLOW_SKIP" ] && [ -x node_modules/.bin/ethlete-agents ]; then
+  ethlete_branch=$(git rev-parse --abbrev-ref HEAD)
+
+  # Only while the branch is on no remote: that is the whole window in which renaming it is free.
+  if [ -z "$(git for-each-ref --format='%(refname)' "refs/remotes/*/$ethlete_branch")" ]; then
+    node_modules/.bin/ethlete-agents git-flow check || true
+  fi
+
+  unset ethlete_branch
+fi

package/content/git-hooks/pre-push.sh

@@ -0,0 +1,5 @@
+# Never `npx`: it reaches the registry when the package is absent, and a network error here would
+# reject the push. A missing binary must make this block do nothing at all.
+if [ -z "$ETHLETE_GIT_FLOW_SKIP" ] && [ -x node_modules/.bin/ethlete-agents ]; then
+  node_modules/.bin/ethlete-agents git-flow check --push || exit 1
+fi