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

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @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

package/README.md

@@ -113,6 +113,118 @@ 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)
 
 Hooks run commands on the developer's machine, so none are emitted by default - opt in
@@ -152,6 +264,54 @@ Available hooks:
 
 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
@@ -160,7 +320,8 @@ 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": "…" }
 }
 ```
 
@@ -168,8 +329,11 @@ differ per developer, without touching any committed file:
   (`["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 `/handoff` instead
-  of saving the handoff file itself.
+  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

package/content/hooks/context-warning.py

@@ -21,8 +21,10 @@ that matter here, all captured in AGENT_PROFILES:
     bills the entire context at the premium rate, which costs far more than
     handing off into a fresh session ever would. Codex has no such boundary, so
     its budget is just the window.
-  * How a handoff is invoked. Claude has /handoff and /clear; Codex has neither
-    and reads the skill from disk.
+  * How a handoff is invoked. Claude has a slash command and /clear; Codex has
+    neither and reads the skill from disk. The skill's own name differs per repo
+    (`ethlete-handoff` where the generator installed it, `handoff` where the repo
+    ships its own copy), so it is resolved at runtime — see handoff_skill().
 
 At the critical tier, if the session's permission_mode is "auto", the
 instruction escalates from "recommend" to "just do it": auto mode already
@@ -85,14 +87,14 @@ AGENT_PROFILES = {
         "default_window": None,
         "auto_modes": ("auto",),
         "emits_system_message": True,
-        "act_now": "Run /handoff now and continue in a fresh session.",
-        "act_later": "consider /handoff to continue in a fresh session",
-        "recommend": "recommend the user run /handoff to save state and start a fresh session",
-        "suggest": "suggest the user run /handoff to save state and start a fresh session",
+        "act_now": "Run /{handoff} now and continue in a fresh session.",
+        "act_later": "consider /{handoff} to continue in a fresh session",
+        "recommend": "recommend the user run /{handoff} to save state and start a fresh session",
+        "suggest": "suggest the user run /{handoff} to save state and start a fresh session",
         "save_now": (
             "run the handoff skill's save mode right now (finish only an in-flight atomic "
             "edit first, nothing new). Then tell the user exactly which handoff file was "
-            "written and that they should run /clear, then '/handoff resume <slug>', to "
+            "written and that they should run /clear, then '/{handoff} resume <slug>', to "
             "continue — clearing and resuming can't be done programmatically, so this is "
             "the one step still on them."
         ),
@@ -112,15 +114,15 @@ AGENT_PROFILES = {
         "act_later": "consider saving a handoff and continuing in a fresh session",
         "recommend": (
             "tell the user you are near the context limit, then follow "
-            ".agents/skills/ethlete-handoff/SKILL.md to save a handoff and have them start a "
+            ".agents/skills/{handoff}/SKILL.md to save a handoff and have them start a "
             "fresh session"
         ),
         "suggest": (
-            "suggest saving a handoff via .agents/skills/ethlete-handoff/SKILL.md and "
+            "suggest saving a handoff via .agents/skills/{handoff}/SKILL.md and "
             "continuing in a fresh session"
         ),
         "save_now": (
-            "follow .agents/skills/ethlete-handoff/SKILL.md and save a handoff right now "
+            "follow .agents/skills/{handoff}/SKILL.md and save a handoff right now "
             "(finish only an in-flight atomic edit first, nothing new). Then tell the user "
             "exactly which handoff file was written and that they should start a fresh "
             "codex session and resume from it."
@@ -129,6 +131,29 @@ AGENT_PROFILES = {
 }
 
 
+def handoff_skill(root):
+    """Name of the handoff skill installed in this repo.
+
+    The generator prefixes every skill it writes, so the command is /ethlete-handoff in a
+    consumer repo — but a repo that excludes the generated copy and ships its own (the SDK
+    itself) has a plain /handoff instead. Naming the wrong one sends the user to a slash
+    command that does not exist, so it is read off disk rather than assumed.
+    """
+    for name in ("ethlete-handoff", "handoff"):
+        for skills_dir in (".claude/skills", ".agents/skills"):
+            if os.path.isdir(os.path.join(root or ".", skills_dir, name)):
+                return name
+    return "ethlete-handoff"
+
+
+def resolve_profile(profile, skill):
+    """Fills the installed handoff skill's name into a profile's message fragments."""
+    return {
+        key: value.replace("{handoff}", skill) if isinstance(value, str) else value
+        for key, value in profile.items()
+    }
+
+
 def agent_name(argv):
     """The --agent value, defaulting to claude — older registrations pass no flag."""
     for index, arg in enumerate(argv):
@@ -336,10 +361,13 @@ def main():
         return
 
     data = json.load(sys.stdin)
-    local_config = load_local_config(repo_root(data))
+    root = repo_root(data)
+    local_config = load_local_config(root)
     if disabled_locally(local_config):
         return
 
+    profile = resolve_profile(profile, handoff_skill(root))
+
     transcript_path = data.get("transcript_path")
     session_id = data.get("session_id", "unknown")
     auto_mode = data.get("permission_mode") in profile["auto_modes"] and not auto_handoff_save_disabled(local_config)

package/content/skills/git-flow/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: git-flow
+description: How to name and base a branch in this repo, and what its merge request must target - feature, sub-feature, release, release fix and hotfix. Read BEFORE creating a branch, opening a merge request, or choosing what to branch from (e.g. the user says "start work on FIP-2177" or "open an MR").
+kind: skill
+scope: both
+vars: [gitFlowDevelopmentBranch, gitFlowProductionBranch, gitFlowTypes, gitFlowEnforcement, gitFlowSubPrefix]
+---
+
+# Git flow
+
+Work is organised in two levels: a **main feature branch** per Jira Story, into which
+**sub-feature branches** (one per Task) are merged after review. The main feature branch is
+what gets deployed to a test environment and, once accepted, merged into
+`{%gitFlowDevelopmentBranch%}`.
+
+**Never name a branch by hand - `start` does it from the grammar:**
+
+```bash
+npx ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
+npx ethlete-agents git-flow check                 # is the current branch conforming?
+npx ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
+npx ethlete-agents git-flow repair <branch>       # rename a non-conforming one, retarget its MRs
+```
+
+`start` prints its plan (branch, base, MR target) and asks before writing anything; add
+`--dry-run` to see the plan alone. It refuses on a dirty working tree, and a Task nests under
+its parent Story's branch, so that branch has to exist first.
+
+## The five shapes
+
+| Shape                                                                             | Issue | Branch from                    | MR targets                                                       |
+| --------------------------------------------------------------------------------- | ----- | ------------------------------ | ---------------------------------------------------------------- |
+| `feat/FIP-2177-user-management`                                                   | Story | `{%gitFlowDevelopmentBranch%}` | `{%gitFlowDevelopmentBranch%}`                                   |
+| `{%gitFlowSubPrefix%}/feat/FIP-2177-user-management/FIP-2178-user-password-reset` | Task  | the main feature branch        | the main feature branch                                          |
+| `release/2026.04.28`                                                              | -     | `{%gitFlowDevelopmentBranch%}` | `{%gitFlowDevelopmentBranch%}` and `{%gitFlowProductionBranch%}` |
+| `{%gitFlowSubPrefix%}/release/2026.04.28/FIP-2222-button-not-visible`             | Bug   | the release branch             | the release branch                                               |
+| `hotfix/FIP-2799-password-recovery-broken`                                        | Bug   | `{%gitFlowProductionBranch%}`  | `{%gitFlowProductionBranch%}`                                    |
+
+- The **type** is one of {%gitFlowTypes%}, and a nested branch carries its parent's **full**
+  name - that path is what makes the parent machine-readable.
+- The **key** is the Jira issue, uppercase, immediately after the type. The **subject** is the
+  Story's subject meta field in kebab-case, not a paraphrase of the summary.
+- A branch with no key still works, but nothing can attribute it to an issue. Add the key.
+
+### Why a nested branch starts with `{%gitFlowSubPrefix%}/`
+
+Git refuses a ref that is both a branch and a directory of branches. So
+`feat/FIP-2177-user-management/FIP-2178-user-password-reset` **cannot exist** while
+`feat/FIP-2177-user-management` does - git rejects it locally and the push comes back as
+`refname conflict`. The prefix moves the nested tree out of the way and keeps the parent's
+full path inside the child's name, so the MR target is still readable off the name.
+
+Do not "fix" a name by dropping the prefix; the branch it produces cannot be created.
+
+## Rules that are not about naming
+
+- **Never rebase a shared branch.** A main feature branch is published and other people's
+  sub-features are based on it - bring it up to date by **merging**
+  `{%gitFlowDevelopmentBranch%}` into it. Rebase only a local branch you have not pushed.
+- **A sub-feature merges into its parent, never straight into
+  `{%gitFlowDevelopmentBranch%}`** - that is the whole point of the two levels, since the
+  parent is what gets tested as a unit.
+- **Delete the source branch on merge** (the checkbox in the merge request) for sub-features,
+  release fixes and merged main features.
+- **A hotfix branches off `{%gitFlowProductionBranch%}`** and, after rollout, that branch is
+  merged back into `{%gitFlowDevelopmentBranch%}` so the two do not drift.
+- **Never push directly to `{%gitFlowDevelopmentBranch%}` or
+  `{%gitFlowProductionBranch%}`.** Open a merge request; it needs another developer's review.
+
+## Enforcement is `{%gitFlowEnforcement%}`
+
+In `advisory` mode every rule reports and nothing blocks - the older naming shapes (`feature/`
+instead of `feat/`, a lowercase key, no key at all, a `dev-*` integration branch) are accepted
+on purpose while the team adapts. Report the suggestion, do not "fix" someone's existing
+branch unasked - `repair` is how a rename happens, and only when asked for.
+
+`dev-*` is the **old spelling of a main feature branch**, not a stray name: sub-features
+legitimately target it. Leave a live one alone.
+
+## Commit messages are a separate thing
+
+Commits stay conventional (`feat(platform): Prefer a player's common name`) and carry **no
+issue key** - the branch already has it. See {%skill:git-commit%}.

package/content/skills/handoff/SKILL.md

@@ -15,6 +15,10 @@ continue in a fresh session. Two modes:
 - **save** ("handoff", "wrap up") - write a handoff file.
 - **resume** ("continue from the handoff") - read one and continue the work.
 
+This skill is installed as `ethlete-handoff`, so under Claude Code the commands
+are `/ethlete-handoff` and `/ethlete-handoff resume [name]` - there is no
+`/handoff`. Name them that way whenever you tell the user what to run.
+
 Handoff files live in `{%handoffDir%}/` (gitignored - they are personal,
 ephemeral working state, not team docs).
 

package/content/skills/query/SKILL.md

@@ -16,17 +16,17 @@ paged queries, bearer auth, GraphQL, and a socket.io realtime client.
 non-trivial query work.** This guide is the index plus the load-bearing facts, so you
 don't re-derive them from source.
 
-| Page                                                                   | Covers                                                                              |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| {%docsBaseUrl%}/query/                                                 | Overview + the two-generations note                                                 |
-| {%docsBaseUrl%}/query/queries                                          | **Start here** - client, creators, the query object's signals, auto-execution       |
-| {%docsBaseUrl%}/query/features                                         | `withArgs`, `withPolling`, `withAutoRefresh`, side-effect handlers                  |
-| {%docsBaseUrl%}/query/http                                             | REST creators, typing requests, response transforms, upload progress                |
-| {%docsBaseUrl%}/query/auth                                             | Bearer auth: login/refresh, auto token refresh, multi-tab sync                      |
-| {%docsBaseUrl%}/query/caching · `/stacks` · `/errors` · `/gql` · `/ws` | Caching/dedup, pagination, error/retry, GraphQL, WebSockets                         |
-| {%docsBaseUrl%}/query/multi-tab                                        | Opt-in cross-tab sync: shared responses, per-key polling election, mutation fan-out |
-| {%docsBaseUrl%}/query/query-forms                                      | Router-synced filter/search forms                                                   |
-| {%docsBaseUrl%}/query/legacy                                           | The maintenance-mode `V2QueryClient`                                                |
+| Page                                                                   | Covers                                                                                |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| {%docsBaseUrl%}/query/                                                 | Overview + the two-generations note                                                   |
+| {%docsBaseUrl%}/query/queries                                          | **Start here** - client, creators, the query object's signals, auto-execution         |
+| {%docsBaseUrl%}/query/features                                         | `withArgs`, `withPolling`, `withLongPolling`, `withAutoRefresh`, side-effect handlers |
+| {%docsBaseUrl%}/query/http                                             | REST creators, typing requests, response transforms, upload progress                  |
+| {%docsBaseUrl%}/query/auth                                             | Bearer auth: login/refresh, auto token refresh, multi-tab sync                        |
+| {%docsBaseUrl%}/query/caching · `/stacks` · `/errors` · `/gql` · `/ws` | Caching/dedup, pagination, error/retry, GraphQL, WebSockets                           |
+| {%docsBaseUrl%}/query/multi-tab                                        | Opt-in cross-tab sync: shared responses, per-key polling election, mutation fan-out   |
+| {%docsBaseUrl%}/query/query-forms                                      | Router-synced filter/search forms                                                     |
+| {%docsBaseUrl%}/query/legacy                                           | The maintenance-mode `V2QueryClient`                                                  |
 
 ## Two generations - use the current one
 
@@ -77,8 +77,8 @@ raw `toObservable`). It emits `null` first - `pipe(filter(r => r !== null))`.
 - **`withArgs(() => ({ pathParams, queryParams, body }))`** - runs like a `computed`;
   re-runs when a signal it reads changes and re-executes the query. This is how you
   drive **search-as-you-type**: back it with a search signal
-  (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return
-  `CLEAR_QUERY_ARGS` to reset args to `null` (pauses polling/auto-refresh).
+  (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return `null`
+  to park the query - args reset to `null`, pausing polling/auto-refresh.
 - **Prefer `withArgs` over passing `args` to `execute()`.** Args declared on the query
   stay reactive: a `GET` re-executes itself when they change, and `withPolling` /
   `withAutoRefresh` restart off the same signal - none of which happens for args handed
@@ -86,6 +86,10 @@ raw `toObservable`). It emits `null` first - `pipe(filter(r => r !== null))`.
   place a mutation is just `.execute()`, which reuses the current `args()`. Reserve
   `execute({ args })` for a one-off payload no signal holds (a form submit).
 - `withPolling({ interval })`, `withAutoRefresh({ onSignalChanges: [...] })`.
+- **`withLongPolling({ nextArgs })`** for a completion-driven chain instead of an interval: each
+  round starts once the previous settled, with args (a cursor) derived from its response. `nextArgs`
+  returning `null` ends the chain. Not `withPolling` with a small interval - and the two throw when
+  combined.
 - Side-effects: `withSuccessHandling`, `withErrorHandling`, `withLogging`.
 
 There is no built-in debounce operator - dedup/caching handles repeated identical

package/package.json

@@ -1,8 +1,19 @@
 {
   "name": "@ethlete/agent-rules",
-  "version": "0.1.0-next.5",
+  "version": "0.1.0-next.6",
   "license": "MIT",
   "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./git-flow": {
+      "types": "./src/lib/git-flow/index.d.ts",
+      "default": "./src/lib/git-flow/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",
   "bin": {

package/src/index.js

@@ -5,6 +5,7 @@ const tslib_1 = require("tslib");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const config_1 = require("./lib/config");
+const git_flow_command_1 = require("./lib/git-flow-command");
 const migrate_1 = require("./lib/migrate");
 const sync_1 = require("./lib/sync");
 const USAGE = `ethlete-agents — compile @ethlete agent rules and skills into your repo
@@ -12,6 +13,8 @@ const USAGE = `ethlete-agents — compile @ethlete agent rules and skills into y
   ethlete-agents sync      Write the generated rules/skills for every detected agent
   ethlete-agents check     Exit non-zero when the generated files are out of date (for CI)
   ethlete-agents init      Write a starter ${config_1.CONFIG_FILE_NAME}
+  ethlete-agents git-flow  Name, check and repair branches against the repo's git flow
+                           (start, check, repair, explain)
   ethlete-agents migrate   Convert the repo to the AGENTS.md + .agents/skills layout:
                            CLAUDE.md content moves into AGENTS.md (CLAUDE.md becomes an
                            @AGENTS.md import), hand-written .claude/skills move to
@@ -66,6 +69,8 @@ const run = (argv) => {
             return (0, sync_1.check)(options);
         case 'init':
             return init(root);
+        case 'git-flow':
+            return (0, git_flow_command_1.gitFlowCommand)({ root, argv: argv.slice(1) });
         case 'migrate':
             return (0, migrate_1.migrate)(Object.assign(Object.assign({}, options), { dryRun: argv.includes('--dry-run') }));
         default:
@@ -76,12 +81,12 @@ const run = (argv) => {
 tslib_1.__exportStar(require("./lib"), exports);
 // Guarded so the package can also be imported as a library without running the CLI.
 if (require.main === module) {
-    try {
-        process.exit(run(process.argv.slice(2)));
-    }
-    catch (error) {
+    Promise.resolve()
+        .then(() => run(process.argv.slice(2)))
+        .then((code) => process.exit(code))
+        .catch((error) => {
         console.error(error instanceof Error ? error.message : error);
         process.exit(1);
-    }
+    });
 }
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/agent-rules/src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/agent-rules/src/index.ts"],"names":[],"mappings":"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"}

package/src/lib/config.d.ts

@@ -1,8 +1,23 @@
 import { ContentScope } from './frontmatter';
+import { GitFlowConfig } from './git-flow';
 export declare const AGENT_TARGETS: readonly ["claude", "codex", "cursor", "copilot"];
 export type AgentTarget = (typeof AGENT_TARGETS)[number];
 export declare const CONFIG_FILE_NAME = "ethlete-agents.config.json";
 export declare const LOCAL_CONFIG_FILE_NAME = "ethlete-agents.config.local.json";
+/**
+ * Non-secret Jira wiring, committed with the repo — `git-flow start` resolves an issue key through
+ * it. Credentials never live here; they come from the environment or the gitignored local config.
+ */
+export type JiraSettings = {
+    host?: string;
+    /**
+     * The instance's field holding a Story's branch subject (`customfield_10050`). Without it the
+     * summary is slugified instead, which is a paraphrase rather than the agreed subject.
+     */
+    subjectField?: string;
+    /** Branch type per Jira issue type, e.g. `{ "Bug": "fix" }`. Anything unlisted becomes `feat`. */
+    typeByIssueType?: Record<string, string>;
+};
 export type SyncConfig = {
     root: string;
     targets: AgentTarget[];
@@ -18,6 +33,11 @@ export type SyncConfig = {
     claudeMdImportsAgentsMd: boolean;
     /** Opt-in agent hooks (they run commands on the developer's machine, so never default). */
     hooks: string[];
+    /** Opt-in git hooks, appended to the repo's own husky hooks. Same reason they never default. */
+    gitHooks: string[];
+    /** The branch grammar, resolved against its defaults — see `@ethlete/agent-rules/git-flow`. */
+    gitFlow: GitFlowConfig;
+    jira: JiraSettings;
 };
 /**
  * The gitignored local config holds per-machine values, read at runtime — by the generated hook
@@ -31,11 +51,19 @@ export type SyncConfig = {
  *   a handoff instead of writing the handoff file automatically.
  * - `sdkSourcePath` points at a local `ethlete-sdk` checkout, which the SDK source and local-build
  *   skills read when they need the SDK's own sources instead of the published package.
+ * - `jira` holds the per-user Jira credentials `git-flow start` needs. This is the one place in the
+ *   repo a secret may sit, and only because the file is gitignored; `JIRA_EMAIL`/`JIRA_API_TOKEN`
+ *   in the environment are the alternative.
  */
 export type LocalConfig = {
     disableHooks?: boolean | string[];
     disableAutoHandoffSave?: boolean;
     sdkSourcePath?: string;
+    jira?: {
+        host?: string;
+        email?: string;
+        token?: string;
+    };
 };
 export type LocalConfigState = {
     exists: false;