[Codefuse开源轻训营] 从1个仓库里收集1条代码审查instance，至少包含Medium一类代码审查难度级别

[Henrykwokkk]

1. 选择1个目标Python仓库
2. 根据Readme.md，执行Get Pull Request Data脚本，即使用 GitHub GraphQL API 从特定仓库获取 PR 数据。

python -m swe_care.collect get_graphql_prs_data \
    --repo "<repo_owner>/<repo_name>" \
    --output-dir "results/graphql_prs_data" \
    --tokens "your_github_pat" \
    --max-number 20

3. 执行``Classify PRs Data```脚本，该脚本通过评估提交内容并标注审查意见，对PR数据进行分析与分类。

python -m swe_care.collect classify_prs_data \
    --graphql-prs-data-file "results/graphql_prs_data/<repo_owner>__<repo_name>_graphql_prs_data.jsonl" \
    --output-dir "./results/classify_prs_data" \
    --tokens "your_github_pat"

4. 执行Build Code Review Dataset，目标在于构建代码审查任务的最终数据集。此步骤需要大型语言模型对每个任务实例的元数据（如问题领域、难度和审查工作量）进行分类。

# Example with OpenAI GPT-4o
export OPENAI_API_KEY=<your_openai_api_key>
python -m swe_care.collect build_code_review_dataset \
    --graphql-prs-data-file "results/graphql_prs_data/<repo_owner>__<repo_name>_graphql_prs_data.jsonl" \
    --pr-classification-file "results/classify_prs_data/<repo_owner>__<repo_name>_pr_classification.jsonl" \
    --model "gpt-4o" \
    --model-provider "openai" \
    --model-args "temperature=0.7,top_p=0.9" \
    --output-dir "./results/dataset" \
    --tokens "your_github_pat"

5. 提交代码审查数据文件的Pull Request

[Monologuethl]

{"instance_id": "spring-projects__spring-framework-29727@4fc2689", "repo": "spring-projects/spring-framework", "language": "Java", "pull_number": 29727, "title": "Add Kotlin DSL support for MockMVC andExpectAll", "body": "As the DSL internally calls ResultActions.andExpect, this is done with a trick where a synthetic ResultActions is provided at top level which stores each ResultMatcher in a mutable list. Once the DSL usage is done, the top level DSL andExpectAll turns that list into a vararg passed down to the actual actions.andExpectAll.\r\n\r\nCloses gh-27317\r\n", "created_at": "2022-12-21T16:12:03Z", "problem_statement": "Introduce Kotlin DSL for ResultActions.andExpectAll()\n## Overview\r\n\r\nCommit dd9b99e13d6b30462fb168799e6bbca1456123da introduced ResultActions.andExpectAll() to support soft assertions in MockMvc.\r\n\r\nResultActionsDsl.kt already has support for andExpect().\r\n\r\n\r\n## Related Issues\r\n\r\n- #27318\r\n\r\n## Deliverables\r\n\r\n- [x] Introduce Kotlin support for ResultActions.andExpectAll() in ResultActionsDsl.kt. => #29727 \r\n- [x] Add a Kotlin example using andExpectAll() in the reference manual alongside the Java example introduced in dd9b99e13d6b30462fb168799e6bbca1456123da. => #29766", "hints_text": "", "resolved_issues": [{"number": 27317, "title": "Introduce Kotlin DSL for ResultActions.andExpectAll()", "body": "## Overview\r\n\r\nCommit dd9b99e13d6b30462fb168799e6bbca1456123da introduced ResultActions.andExpectAll() to support soft assertions in MockMvc.\r\n\r\nResultActionsDsl.kt already has support for andExpect().\r\n\r\n\r\n## Related Issues\r\n\r\n- #27318\r\n\r\n## Deliverables\r\n\r\n- [x] Introduce Kotlin support for ResultActions.andExpectAll() in ResultActionsDsl.kt. => #29727 \r\n- [x] Add a Kotlin example using andExpectAll() in the reference manual alongside the Java example introduced in dd9b99e13d6b30462fb168799e6bbca1456123da. => #29766 "}], "base_commit": "697292ba0ca5aa69454e7a184197be90c75de3ab", "commit_to_review": {"head_commit": "4fc268959235c12426202938f479ba079a3a3e9b", "head_commit_message": "Add Kotlin DSL support for MockMVC andExpectAll\n\nAs the DSL internally calls ResultActions.andExpect, this is done with\na trick where a synthetic ResultActions is provided at top level which\nstores each ResultMatcher in a mutable list. Once the DSL usage is done,\n the top level DSL andExpectAll turns that list into a vararg passed\n down to the actual actions.andExpectAll.\n\nFixes gh-27317.", "patch_to_review": "diff --git a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt\nindex 8971a80f4b5c..0ba22eafa1c4 100644\n--- a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt\n+++ b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt\n@@ -145,4 +145,11 @@ class MockMvcResultMatchersDsl internal constructor (private val actions: Result\n \tfun match(matcher: ResultMatcher) {\n \t\tactions.andExpect(matcher)\n \t}\n+\n+\t/\n+\t * @see ResultActions.andExpectAll\n+\t */\n+\tfun matchAll(vararg matchers: ResultMatcher) {\n+\t\tactions.andExpectAll(*matchers)\n+\t}\n }\ndiff --git a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt\nindex 128b9492b8c4..2bc0ffb426d3 100644\n--- a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt\n+++ b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt\n@@ -19,6 +19,34 @@ class ResultActionsDsl internal constructor (private val actions: ResultActions,\n \t\treturn this\n \t}\n \n+\n+\t/\n+\t * Provide access to [MockMvcResultMatchersDsl] Kotlin DSL.\n+\t * @see MockMvcResultMatchersDsl.matchAll\n+\t */\n+\tfun andExpectAll(dsl: MockMvcResultMatchersDsl.() -> Unit): ResultActionsDsl {\n+\t\tval softMatchers = mutableListOf()\n+\t\tval softActions = object : ResultActions {\n+\t\t\toverride fun andExpect(matcher: ResultMatcher): ResultActions {\n+\t\t\t\tsoftMatchers.add(matcher)\n+\t\t\t\treturn this\n+\t\t\t}\n+\n+\t\t\toverride fun andDo(handler: ResultHandler): ResultActions {\n+\t\t\t\tthrow UnsupportedOperationException("andDo should not be part of andExpectAll DSL calls")\n+\t\t\t}\n+\n+\t\t\toverride fun andReturn(): MvcResult {\n+\t\t\t\tthrow UnsupportedOperationException("andReturn should not be part of andExpectAll DSL calls")\n+\t\t\t}\n+\n+\t\t}\n+\t\t// the use of softActions as the matchers DSL actions parameter will store ResultMatchers in list\n+\t\tMockMvcResultMatchersDsl(softActions).dsl()\n+\t\tactions.andExpectAll(*softMatchers.toTypedArray())\n+\t\treturn this;\n+\t}\n+\n \t/\n \t * Provide access to [MockMvcResultHandlersDsl] Kotlin DSL.\n \t * @see MockMvcResultHandlersDsl.handle\ndiff --git a/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt b/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt\nindex d1e731f3bc27..40e1ded9caf1 100644\n--- a/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt\n+++ b/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt\n@@ -17,6 +17,7 @@\n package org.springframework.test.web.servlet\n \n import org.assertj.core.api.Assertions.assertThat\n+import org.assertj.core.api.Assertions.assertThatCode\n import org.assertj.core.api.Assertions.assertThatExceptionOfType\n import org.hamcrest.CoreMatchers\n import org.junit.jupiter.api.Test\n@@ -25,6 +26,7 @@ import org.springframework.http.HttpStatus\n import org.springframework.http.MediaType.APPLICATION_ATOM_XML\n import org.springframework.http.MediaType.APPLICATION_JSON\n import org.springframework.http.MediaType.APPLICATION_XML\n+import org.springframework.http.MediaType.TEXT_PLAIN\n import org.springframework.test.web.Person\n import org.springframework.test.web.servlet.setup.MockMvcBuilders\n import org.springframework.web.bind.annotation.GetMapping\n@@ -183,6 +185,22 @@ class MockMvcExtensionsTests {\n \t\t}\n \t}\n \n+\t@Test\n+\tfun andExpectAll reports multiple assertion errors() {\n+\t\tassertThatCode {\n+\t\t\tmockMvc.request(HttpMethod.GET, "/person/{name}", "Lee") {\n+\t\t\t\taccept = APPLICATION_JSON\n+\t\t\t}.andExpectAll {\n+\t\t\t\tstatus { is4xxClientError() }\n+\t\t\t\tcontent { contentType(TEXT_PLAIN) }\n+\t\t\t\tjsonPath("$.name") { value("Lee") }\n+\t\t\t}\n+\t\t}\n+\t\t\t\t.hasMessage("Multiple Exceptions (2):\n" +\n+\t\t\t\t\t\t"Range for response status value 200 expected:<CLIENT_ERROR> but was:\n" +\n+\t\t\t\t\t\t"Content type expected:<text/plain> but was:<application/json>")\n+\t}\n+\n \n \t@RestController\n \tprivate class PersonController {\n"}, "reference_review_comments": [{"text": "@user1:\nMaybe add a related usage in tests?\n\n@author:\ndone", "path": "spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt", "diff_hunk": "@@ -145,4 +145,11 @@ class MockMvcResultMatchersDsl internal constructor (private val actions: Result\n \tfun match(matcher: ResultMatcher) {\n \t\tactions.andExpect(matcher)\n \t}\n+\n+\t/\n+\t * @see ResultActions.andExpectAll\n+\t */\n+\tfun matchAll(vararg matchers: ResultMatcher) {", "line": 153, "start_line": null, "original_line": 152, "original_start_line": null}, {"text": "@user1:\nClever trick, seems to provide a desired behavior, so good catch!", "path": "spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt", "diff_hunk": "@@ -19,6 +19,34 @@ class ResultActionsDsl internal constructor (private val actions: ResultActions,\n \t\treturn this\n \t}\n \n+\n+\t/\n+\t * Provide access to [MockMvcResultMatchersDsl] Kotlin DSL.\n+\t * @see MockMvcResultMatchersDsl.matchAll\n+\t */\n+\tfun andExpectAll(dsl: MockMvcResultMatchersDsl.() -> Unit): ResultActionsDsl {", "line": 28, "start_line": null, "original_line": 27, "original_start_line": null}, {"text": "@user2:\nMaybe add @user1 6.0.4?", "path": "spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt", "diff_hunk": "@@ -145,4 +145,11 @@ class MockMvcResultMatchersDsl internal constructor (private val actions: Result\n \tfun match(matcher: ResultMatcher) {\n \t\tactions.andExpect(matcher)\n \t}\n+\n+\t/\n+\t * @see ResultActions.andExpectAll", "line": 151, "start_line": null, "original_line": 150, "original_start_line": null}, {"text": "@user2:\nMaybe add @user1 6.0.4?", "path": "spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt", "diff_hunk": "@@ -19,6 +19,34 @@ class ResultActionsDsl internal constructor (private val actions: ResultActions,\n \t\treturn this\n \t}\n \n+\n+\t/\n+\t * Provide access to [MockMvcResultMatchersDsl] Kotlin DSL.\n+\t * @see MockMvcResultMatchersDsl.matchAll", "line": 26, "start_line": null, "original_line": 25, "original_start_line": null}], "merged_commit": "16bbf3ed40891259aaa4cde17da700027bb481bc", "merged_patch": "diff --git a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt\nindex 8971a80f4b5c..593f666ec2ea 100644\n--- a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt\n+++ b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/MockMvcResultMatchersDsl.kt\n@@ -145,4 +145,12 @@ class MockMvcResultMatchersDsl internal constructor (private val actions: Result\n \tfun match(matcher: ResultMatcher) {\n \t\tactions.andExpect(matcher)\n \t}\n+\n+\t/\n+\t * @SInCE 6.0.4\n+\t * @see ResultActions.andExpectAll\n+\t */\n+\tfun matchAll(vararg matchers: ResultMatcher) {\n+\t\tactions.andExpectAll(*matchers)\n+\t}\n }\ndiff --git a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt\nindex 128b9492b8c4..5d413702467d 100644\n--- a/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt\n+++ b/spring-test/src/main/kotlin/org/springframework/test/web/servlet/ResultActionsDsl.kt\n@@ -19,6 +19,35 @@ class ResultActionsDsl internal constructor (private val actions: ResultActions,\n \t\treturn this\n \t}\n \n+\n+\t/\n+\t * Provide access to [MockMvcResultMatchersDsl] Kotlin DSL.\n+\t * @SInCE 6.0.4\n+\t * @see MockMvcResultMatchersDsl.matchAll\n+\t */\n+\tfun andExpectAll(dsl: MockMvcResultMatchersDsl.() -> Unit): ResultActionsDsl {\n+\t\tval softMatchers = mutableListOf()\n+\t\tval softActions = object : ResultActions {\n+\t\t\toverride fun andExpect(matcher: ResultMatcher): ResultActions {\n+\t\t\t\tsoftMatchers.add(matcher)\n+\t\t\t\treturn this\n+\t\t\t}\n+\n+\t\t\toverride fun andDo(handler: ResultHandler): ResultActions {\n+\t\t\t\tthrow UnsupportedOperationException("andDo should not be part of andExpectAll DSL calls")\n+\t\t\t}\n+\n+\t\t\toverride fun andReturn(): MvcResult {\n+\t\t\t\tthrow UnsupportedOperationException("andReturn should not be part of andExpectAll DSL calls")\n+\t\t\t}\n+\n+\t\t}\n+\t\t// the use of softActions as the matchers DSL actions parameter will store ResultMatchers in list\n+\t\tMockMvcResultMatchersDsl(softActions).dsl()\n+\t\tactions.andExpectAll(*softMatchers.toTypedArray())\n+\t\treturn this;\n+\t}\n+\n \t/\n \t * Provide access to [MockMvcResultHandlersDsl] Kotlin DSL.\n \t * @see MockMvcResultHandlersDsl.handle\ndiff --git a/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt b/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt\nindex d1e731f3bc27..737e235d4e33 100644\n--- a/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt\n+++ b/spring-test/src/test/kotlin/org/springframework/test/web/servlet/MockMvcExtensionsTests.kt\n@@ -17,6 +17,7 @@\n package org.springframework.test.web.servlet\n \n import org.assertj.core.api.Assertions.assertThat\n+import org.assertj.core.api.Assertions.assertThatCode\n import org.assertj.core.api.Assertions.assertThatExceptionOfType\n import org.hamcrest.CoreMatchers\n import org.junit.jupiter.api.Test\n@@ -25,6 +26,7 @@ import org.springframework.http.HttpStatus\n import org.springframework.http.MediaType.APPLICATION_ATOM_XML\n import org.springframework.http.MediaType.APPLICATION_JSON\n import org.springframework.http.MediaType.APPLICATION_XML\n+import org.springframework.http.MediaType.TEXT_PLAIN\n import org.springframework.test.web.Person\n import org.springframework.test.web.servlet.setup.MockMvcBuilders\n import org.springframework.web.bind.annotation.GetMapping\n@@ -97,6 +99,24 @@ class MockMvcExtensionsTests {\n \t\tassertThat(handlerInvoked).isTrue()\n \t}\n \n+\t@Test\n+\tfun request with two custom matchers and matchAll() {\n+\t\tvar matcher1Invoked = false\n+\t\tvar matcher2Invoked = false\n+\t\tval matcher1 = ResultMatcher { matcher1Invoked = true; throw AssertionError("expected") }\n+\t\tval matcher2 = ResultMatcher { matcher2Invoked = true }\n+\t\tassertThatExceptionOfType(AssertionError::class.java).isThrownBy {\n+\t\t\tmockMvc.request(HttpMethod.GET, "/person/{name}", "Lee")\n+\t\t\t\t\t.andExpect {\n+\t\t\t\t\t\tmatchAll(matcher1, matcher2)\n+\t\t\t\t\t}\n+\t\t}\n+\t\t\t\t.withMessage("expected")\n+\n+\t\tassertThat(matcher1Invoked).describedAs("matcher1").isTrue()\n+\t\tassertThat(matcher2Invoked).describedAs("matcher2").isTrue()\n+\t}\n+\n \t@Test\n \tfun get() {\n \t\tmockMvc.get("/person/{name}", "Lee") {\n@@ -183,6 +203,22 @@ class MockMvcExtensionsTests {\n \t\t}\n \t}\n \n+\t@Test\n+\tfun andExpectAll reports multiple assertion errors() {\n+\t\tassertThatCode {\n+\t\t\tmockMvc.request(HttpMethod.GET, "/person/{name}", "Lee") {\n+\t\t\t\taccept = APPLICATION_JSON\n+\t\t\t}.andExpectAll {\n+\t\t\t\tstatus { is4xxClientError() }\n+\t\t\t\tcontent { contentType(TEXT_PLAIN) }\n+\t\t\t\tjsonPath("$.name") { value("Lee") }\n+\t\t\t}\n+\t\t}\n+\t\t\t\t.hasMessage("Multiple Exceptions (2):\n" +\n+\t\t\t\t\t\t"Range for response status value 200 expected:<CLIENT_ERROR> but was:\n" +\n+\t\t\t\t\t\t"Content type expected:<text/plain> but was:<application/json>")\n+\t}\n+\n \n \t@RestController\n \tprivate class PersonController {\n", "metadata": {"problem_domain": "New Feature Additions", "difficulty": "medium", "estimated_review_effort": 3}}

[jingjin-dev]

{"instance_id": "AUTOMATIC1111__stable-diffusion-webui-10324@867be74", "repo": "AUTOMATIC1111/stable-diffusion-webui", "language": "Python", "pull_number": 10324, "title": "Allow web UI to be ran fully offline", "body": "Describe what this pull request is trying to achieve.\r\n\r\nCloses https://github.com/AUTOMATIC1111/stable-diffusion-webui/issues/10024\r\n\r\nThis PR allows the web UI to be ran fully offline via two one change.\r\n\r\n~~The 1st change blocks an initial phone-home request that Gradio makes on first import, something that cannot be blocked by setting GRADIO_ANALYTICS_ENABLED to False, and was mentioned here but hasn't been taken care of until now. The text-generation-webui employs this same technique. https://github.com/oobabooga/text-generation-webui/blob/c746a5bd00c39776bec0091a570f3348aa785caa/server.py#L12~~\r\nRemoved per suggestion. Expected to be resolved upstream by gradio-app/gradio#4194 \r\n\r\nThe 2nd change removes the requirement of pulling fonts from Google Fonts, by manually specifying the font list to use for the default Gradio theme, and importing in the font via the frontend CSS from Google Fonts. When attempting to run offline without this modification, in my tests this causes the web UI to hang and never finish loading. \r\n\r\nAdditional notes and description of your changes\r\n\r\nIn regards to the frontend: Gradio currently has a hardcoded JS import for iFrame Resizer, something that is was in the works to be removed for Gradio 3.0, but in an offline environment will not cause the UI to hang if it's not loaded, nor does it hamper the UI in any way, as I believe the only purpose this serves is for some workaround on Huggingface Spaces. There is also a hardcoded preconnect for fonts.googleapis.com but that is again something that doesn't prevent the UI from being used offline, only the backend code causes that. While neither of these have a simple method of removal from the code, everything mentioned in this paragraph can easily be blocked by something like uBlock Origin if the user would like to prevent all outbound connections on the webpage itself (assuming there is an active Internet connection).\r\n\r\nEnvironment this was tested in\r\n\r\n - OS: Windows 11\r\n - Browser: Firefox, Chrome\r\n - Graphics card: n/a", "created_at": "2023-05-12T18:19:28Z", "problem_statement": "[Bug]: Gradio not starting offline, needs external CSS to start webUI\n### Is there an existing issue for this?\r\n\r\n- [X] I have searched the existing issues and checked the recent builds/commits\r\n\r\n### What happened?\r\n\r\nI cant use WebUI offline anymore after the last big Update from a few days ago.\r\nGradio hangs, showing only rotating squares when you open WebUI-URL.\r\n\r\nIts looks like it tries to access following css indefinitely and doesnt work without an access to those:\r\nhttps://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&display=swap \r\nhttps://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600&display=swap\r\n\r\n\r\n\r\n### Steps to reproduce the problem\r\n\r\n1. Go offline\r\n2. start "webui-user.bat" and wait until "Running on local URL: http://127.0.0.1:7860\" shows up\r\n3. start browser, go to above URL\r\n4. look at the rotating squares in browser indefinitely\r\n\r\n\r\n### What should have happened?\r\n\r\n4. WebUI Interface should have opened\r\n\r\n### Commit where the problem happens\r\n\r\nsomewhere after 22bcc7be\r\n\r\n### What platforms do you use to access the UI ?\r\n\r\nWindows\r\n\r\n### What browsers do you use to access the UI ?\r\n\r\nMozilla Firefox\r\n\r\n### Command Line Arguments\r\n\r\nShell\r\nset PYTHON=\r\nset GIT=\r\nset VENV_DIR=\r\n\r\nset COMMANDLINE_ARGS= --no-half-vae --opt-sdp-no-mem-attention --opt-channelslast --theme dark ^\r\n--ckpt-dir \"D:\\SD_STUFF\\Models\\_active\" ^\r\n--embeddings-dir \"D:\\SD_STUFF\\embeddings\\_active\" ^\r\n--hypernetwork-dir \"D:\\SD_STUFF\\hypernetworks\\_active\" ^\r\n--lora-dir \"D:\\SD_STUFF\\LoRA\\_active\"\r\n\r\n\r\n\r\n### List of extensions\r\n\r\nNone. I cleared the "extensions" DIR for the test\r\n\r\n### Console logs\r\n\r\nShell\r\nno errors shown\r\n\r\n\r\n\r\n### Additional information\r\nI was able to reproduce the problem when I was online by blocking access to "fonts.googleapis.com" with umatrix.\r\nOnly after unblocking the above url i was able to load webui interface.\r\n\r\n\r\n\r\n", "hints_text": "same here. how do we fix this?\nI've run into this same issue on Ubuntu 22.04\nIt has been a long running issue with gradio based on my reads. I performed a git pull yesterday and ended up with the same results. Gradio was updated to 3.16 and would no longer load frontend without internet.\r\n\r\nI fell back on an older backup where my venv was running Gradio 3.8 and it works fine. Oddly enough the same font.googleapi's references are present in both, so there may have been a change in timeouts (or lack thereof) in the Gradio logic. Pure speculation on my part as I haven't dug very deep on it, but there are other SD/TI bug reports on the same issue. So it seems it is not specific to 1111's repo.\r\n\r\nI know that Gradio 3.8 works offline =but= it is also running an older commit of automatic1111. I tried to downgrade gradio on the latest automatic1111 code base and there are a bunch of UI errors that result.\r\n\r\nI'll link to other non-automatic1111 reports of the same issue:\r\n\r\nhttps://github.com/gradio-app/gradio/issues/1450\r\n\r\nThat was my first landing regarding the issue. You can read up on it there as well as the "mentions" at the bottom being linked from other repos. Seems to be a common problem and most of them (outside of the link shown above) seem to be very recent, so some switch probably got thrown recently.\r\n\r\nI dont upate often as my use-case is primarily seamless textures, but I do like to check out new features/extentions from time to time (just chose a bad time to try). Will have to pass on it until offline or some sane work around returns, however.\r\n\r\nThis is and has been a truly incredible project and many many thanks to all involved.\n> I fell back on an older backup where my venv was running Gradio 3.8\r\n\r\nhow do you do that!??!\n> same here. how do we fix this?\r\n\r\n\r\n\r\nIn your \stable-diffusion-webui\modules\shared.py\r\n\r\n\r\nadd somewhere at top:\r\nShell\r\nimport urllib.request\r\n\r\n\r\nand replace (at line 632):\r\nShell\r\ndef reload_gradio_theme(theme_name=None):\r\n global gradio_theme\r\n if not theme_name:\r\n theme_name = opts.gradio_theme\r\n\r\n if theme_name == \"Default\":\r\n gradio_theme = gr.themes.Default()\r\n else:\r\n try:\r\n gradio_theme = gr.themes.ThemeClass.from_hub(theme_name)\r\n except requests.exceptions.ConnectionError:\r\n print(\"Can't access HuggingFace Hub, falling back to default Gradio theme\")\r\n gradio_theme = gr.themes.Default()\r\n\r\n\r\n\r\nwith\r\nShell\r\ndef reload_gradio_theme(theme_name=None):\r\n global gradio_theme\r\n if not theme_name:\r\n theme_name = opts.gradio_theme\r\n default_font_params = {}\r\n ret_code = 0\r\n try:\r\n req = urllib.request.Request(\"https://fonts.googleapis.com/css2?family=IBM+Plex+Mono\", method=\"HEAD\")\r\n ret_code = urllib.request.urlopen(req, timeout=3.0).get_code()\r\n except:\r\n ret_code = 0\r\n if (ret_code != 200):\r\n print(\"No internet access detected, using default fonts\")\r\n default_font_params = {\r\n 'font':['Helvetica', 'ui-sans-serif', 'system-ui', 'sans-serif'],\r\n 'font_mono':['IBM Plex Mono', 'ui-monospace', 'Consolas', 'monospace']\r\n }\r\n\r\n if theme_name == \"Default\":\r\n gradio_theme = gr.themes.Default(**default_font_params)\r\n else:\r\n try:\r\n gradio_theme = gr.themes.ThemeClass.from_hub(theme_name)\r\n except requests.exceptions.ConnectionError:\r\n print(\"Can't access HuggingFace Hub, falling back to default Gradio theme\")\r\n gradio_theme = gr.themes.Default(**default_font_params)\r\n\r\n\r\n\r\n\r\nworks for me.\r\n\r\nborrowed from:\r\nhttps://github.com/vladmandic/automatic/commit/8f236ef022b333f30c8ec17f716dfee52c7ad126\r\n\r\n\n> In your \stable-diffusion-webui\modules\shared.py\r\n> \r\n\r\nworks here also. will see if it throws any errors in the next few days\nAny chance that we get a fully offline mode for Gradio? Something like gradio my_app.py --offline would be great. A lot of corporate projects operates on a server with no external internet connection. The offline mode doesn't need any fancy CSS or interactive JS rendering, it just have to provide a simple UI interface.\n> > I fell back on an older backup where my venv was running Gradio 3.8\r\n> \r\n> how do you do that!??!\r\n\r\nI wish my solution was more profound, but I found out early on in this repo that if you have a version that does what you =need= but want to experiment, just backup the entire directory. I'm running on linux, so it may be different on other platforms, but yeah i just copy the entire stable-diffusion-web-ui folder somewhere on an external drive (usually i remove the model checkpoints first or exclude them in the copy because i back those up separately). Then i'll do my git pull and upgrade the project. If something goes sideways, i just delete the new and copy the original back (to the original folder location). Gradio is packaged nicely inside the /venv folder within the stable-diffusion-web-ui, so the gradio version comes along with it.\r\n\r\ni'm sure there are easier/cleaner/official ways to revert, but being self contained after install makes it pretty easy to backup. I know this doesn't help the "after the fact" scenario, but its just what i started doing. The project evolves around a good amount of external dependency. I normally only keep one copy on hand and just replace it as I go through successful upgrades (that way you can revert without an internet connection too! XD ). Sorry it probably wasn't the answer you're looking for.\n> Any chance that we get a fully offline mode for Gradio? Something like gradio my_app.py --offline would be great. A lot of corporate projects operates on a server with no external internet connection. The offline mode doesn't need any fancy CSS or interactive JS rendering, it just have to provide a simple UI interface.\r\n\r\njust edit that file and change the code. it works offline with no problems\nOobabooga solved this problem in text-generation-webui by blocking the use of Google fonts. See oobabooga/text-generation-webui#867.", "resolved_issues": [{"number": 10024, "title": "[Bug]: Gradio not starting offline, needs external CSS to start webUI", "body": "### Is there an existing issue for this?\r\n\r\n- [X] I have searched the existing issues and checked the recent builds/commits\r\n\r\n### What happened?\r\n\r\nI cant use WebUI offline anymore after the last big Update from a few days ago.\r\nGradio hangs, showing only rotating squares when you open WebUI-URL.\r\n\r\nIts looks like it tries to access following css indefinitely and doesnt work without an access to those:\r\nhttps://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&display=swap \r\nhttps://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600&display=swap\r\n\r\n\r\n\r\n### Steps to reproduce the problem\r\n\r\n1. Go offline\r\n2. start "webui-user.bat" and wait until "Running on local URL: http://127.0.0.1:7860" shows up\r\n3. start browser, go to above URL\r\n4. look at the rotating squares in browser indefinitely\r\n\r\n\r\n### What should have happened?\r\n\r\n4. WebUI Interface should have opened\r\n\r\n### Commit where the problem happens\r\n\r\nsomewhere after 22bcc7be\r\n\r\n### What platforms do you use to access the UI ?\r\n\r\nWindows\r\n\r\n### What browsers do you use to access the UI ?\r\n\r\nMozilla Firefox\r\n\r\n### Command Line Arguments\r\n\r\nShell\r\nset PYTHON=\r\nset GIT=\r\nset VENV_DIR=\r\n\r\nset COMMANDLINE_ARGS= --no-half-vae --opt-sdp-no-mem-attention --opt-channelslast --theme dark ^\r\n--ckpt-dir \"D:\\SD_STUFF\\Models\\_active\" ^\r\n--embeddings-dir \"D:\\SD_STUFF\\embeddings\\_active\" ^\r\n--hypernetwork-dir \"D:\\SD_STUFF\\hypernetworks\\_active\" ^\r\n--lora-dir \"D:\\SD_STUFF\\LoRA\\_active\"\r\n\r\n\r\n\r\n### List of extensions\r\n\r\nNone. I cleared the "extensions" DIR for the test\r\n\r\n### Console logs\r\n\r\nShell\r\nno errors shown\r\n\r\n\r\n\r\n### Additional information\r\nI was able to reproduce the problem when I was online by blocking access to "fonts.googleapis.com" with umatrix.\r\nOnly after unblocking the above url i was able to load webui interface.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n"}], "base_commit": "9080af56ddbe4128326a1007ac20bcf214d5b6a7", "commit_to_review": {"head_commit": "867be74244dc725fcf2685018b97501e83a16235", "head_commit_message": "Define default fonts for Gradio theme\n\nAllows web UI to (almost) be ran fully offline.\nThe web UI will hang on load if offline when\nthese fonts are not manually defined, as it will attempt (and fail)\nto pull from Google Fonts.", "patch_to_review": "diff --git a/modules/shared.py b/modules/shared.py\nindex 1df1dd45d06..b09b384e70f 100644\n--- a/modules/shared.py\n+++ b/modules/shared.py\n@@ -666,13 +666,19 @@ def reload_gradio_theme(theme_name=None):\n theme_name = opts.gradio_theme\r\n \r\n if theme_name == "Default":\r\n- gradio_theme = gr.themes.Default()\r\n+ gradio_theme = gr.themes.Default(\r\n+ font=['Helvetica', 'ui-sans-serif', 'system-ui', 'sans-serif'],\r\n+ font_mono=['IBM Plex Mono', 'ui-monospace', 'Consolas', 'monospace'],\r\n+ )\r\n else:\r\n try:\r\n gradio_theme = gr.themes.ThemeClass.from_hub(theme_name)\r\n except Exception as e:\r\n errors.display(e, "changing gradio theme")\r\n- gradio_theme = gr.themes.Default()\r\n+ gradio_theme = gr.themes.Default(\r\n+ font=['Helvetica', 'ui-sans-serif', 'system-ui', 'sans-serif'],\r\n+ font_mono=['IBM Plex Mono', 'ui-monospace', 'Consolas', 'monospace'],\r\n+ )\r\n \r\n \r\n \r\ndiff --git a/webui.py b/webui.py\nindex 293a16ccda2..cdb96740565 100644\n--- a/webui.py\n+++ b/webui.py\n@@ -28,7 +28,16 @@\n \r\n startup_timer.record("import torch")\r\n \r\n+import requests\r\n+def gradio_get(url, **kwargs):\r\n+ kwargs.setdefault('allow_redirects', True)\r\n+ return requests.api.request('get', 'http://127.0.0.1/', **kwargs)\r\n+\r\n+original_get = requests.get\r\n+requests.get = gradio_get\r\n import gradio\r\n+requests.get = original_get\r\n+\r\n startup_timer.record("import gradio")\r\n \r\n import ldm.modules.encoders.modules # noqa: F401\r\n"}, "reference_review_comments": [{"text": "@user1:\nAs an aside, this could probably be implemented as something like\r\n\r\nsuggestion\r\nimport requests\r\nfrom unittest.mock import patch\r\nwith patch(\"requests.request\", side_effect=requests.ConnectionError()):\r\n import gradio\r\n", "path": "webui.py", "diff_hunk": "@@ -28,7 +28,16 @@\n \r\n startup_timer.record("import torch")\r\n \r\n+import requests\r\n+def gradio_get(url, **kwargs):\r\n+ kwargs.setdefault('allow_redirects', True)\r\n+ return requests.api.request('get', 'http://127.0.0.1/', **kwargs)\r\n+\r\n+original_get = requests.get\r\n+requests.get = gradio_get\r\n import gradio\r\n+requests.get = original_get\r", "line": null, "start_line": null, "original_line": 39, "original_start_line": 31}], "merged_commit": "867c8a1083e892f06d78c41c5e0a05138c2ae337", "merged_patch": "diff --git a/modules/shared.py b/modules/shared.py\nindex 1df1dd45d06..96a20a6bd9d 100644\n--- a/modules/shared.py\n+++ b/modules/shared.py\n@@ -665,14 +665,19 @@ def reload_gradio_theme(theme_name=None):\n if not theme_name:\r\n theme_name = opts.gradio_theme\r\n \r\n+ default_theme_args = dict(\r\n+ font=["Source Sans Pro", 'ui-sans-serif', 'system-ui', 'sans-serif'],\r\n+ font_mono=['IBM Plex Mono', 'ui-monospace', 'Consolas', 'monospace'],\r\n+ )\r\n+\r\n if theme_name == "Default":\r\n- gradio_theme = gr.themes.Default()\r\n+ gradio_theme = gr.themes.Default(**default_theme_args)\r\n else:\r\n try:\r\n gradio_theme = gr.themes.ThemeClass.from_hub(theme_name)\r\n except Exception as e:\r\n errors.display(e, "changing gradio theme")\r\n- gradio_theme = gr.themes.Default()\r\n+ gradio_theme = gr.themes.Default(*default_theme_args)\r\n \r\n \r\n \r\ndiff --git a/style.css b/style.css\nindex 4ac919b5e8c..8c7be275cec 100644\n--- a/style.css\n+++ b/style.css\n@@ -1,3 +1,6 @@\n+/ temporary fix to load default gradio font in frontend instead of backend /\r\n+\r\n+@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600&display=swap');\r\n \r\n / general gradio fixes */\r\n \r\n", "metadata": {"problem_domain": "Bug Fixes", "difficulty": "medium", "estimated_review_effort": 4}}

[hpzm]

{"instance_id": "public-apis__public-apis-1593@97cb773", "repo": "public-apis/public-apis", "language": "Python", "pull_number": 1593, "title": "Add check for checking duplicated links in README file", "body": "Add extra check into validate_links.py file to check if there are some duplicated links in the README file\r\n\r\nI create an ignored list for some duplicated links which are not related to any API link. There is this link https://github.com/davemachado/public-api in the README listed twice. Should we ignore it too?\r\n\r\nCloses #1592\r\n\r\n", "created_at": "2021-03-20T09:42:37Z", "problem_statement": "Add extra validation to check if more than two links are the same\nThere should be a check in the validation to check if more than two links are the same. \r\nIf they exist in the README the "merge" button should be blocked to merge the PR.", "hints_text": "", "resolved_issues": [{"number": 1592, "title": "Add extra validation to check if more than two links are the same", "body": "There should be a check in the validation to check if more than two links are the same. \r\nIf they exist in the README the "merge" button should be blocked to merge the PR.\r\n\r\n"}], "base_commit": "2174b22c9b756bd8343c4424ff3ca4d6e47b31a0", "commit_to_review": {"head_commit": "97cb773f4517dfa04fa3b49b373b39e9461388dd", "head_commit_message": "Add check for checking duplicated links in README file\n\nCloses #1592", "patch_to_review": "diff --git a/build/validate_links.py b/build/validate_links.py\nindex ab36b0c840..c4eafce954 100755\n--- a/build/validate_links.py\n+++ b/build/validate_links.py\n@@ -5,6 +5,11 @@\n import socket\n import sys\n \n+ignored_links = [\n+ 'https://github.com/public-apis/public-apis/actions?query=workflow%3A%22Run+tests%22', \n+ 'https://github.com/public-apis/public-apis/workflows/Validate%20links/badge.svg?branch=master', \n+ 'https://github.com/public-apis/public-apis/actions?query=workflow%3A%22Validate+links%22',\n+]\n \n def parse_links(filename):\n """Returns a list of URLs from text file"""\n@@ -16,6 +21,29 @@ def parse_links(filename):\n links = [raw_link[0] for raw_link in raw_links]\n return links\n \n+def dup_links(links):\n+ """Check for duplicated links"""\n+ print(f'Checking for duplicated links...')\n+ hasError = False\n+ seen = {}\n+ dupes = []\n+\n+ for x in links:\n+ if x in ignored_links:\n+ continue\n+\n+ if x not in seen:\n+ seen[x] = 1\n+ else:\n+ if seen[x] == 1:\n+ dupes.append(x)\n+\n+ if not dupes:\n+ print(f"No duplicated links")\n+ else:\n+ print(f"Found duplicated links: {dupes}") \n+ hasError = True \n+ return hasError\n \n def validate_links(links):\n """Checks each entry in JSON file for live link"""\n@@ -58,6 +86,9 @@ def validate_links(links):\n if num_args < 2:\n print("No .md file passed")\n sys.exit(1)\n- hasError = validate_links(parse_links(sys.argv[1]))\n+ links = parse_links(sys.argv[1])\n+ hasError = dup_links(links)\n+ if not hasError:\n+ hasError = validate_links(links)\n if hasError:\n sys.exit(1)\n"}, "reference_review_comments": [{"text": "@user1:\nIsn't it better to make it explicit?\r\nsuggestion\r\n for link in links:\r\n", "path": "build/validate_links.py", "diff_hunk": "@@ -16,6 +21,29 @@ def parse_links(filename):\n links = [raw_link[0] for raw_link in raw_links]\n return links\n \n+def dup_links(links):\n+ """Check for duplicated links"""\n+ print(f'Checking for duplicated links...')\n+ hasError = False\n+ seen = {}\n+ dupes = []\n+\n+ for x in links:", "line": null, "start_line": null, "original_line": 31, "original_start_line": null}, {"text": "@user1:\nMany URLs contain the / character at the end. This section does not consider them.\r\n\r\nThis is returning at the moment:\r\n bash\r\nFound duplicated links: ['https://github.com/davemachado/public-api']\r\n\r\n\r\nIf you consider the character / at the end:\r\n bash\r\nFound duplicated links: ['https://mailboxlayer.com', 'https://github.com/davemachado/public-api', 'https://languagelayer.com']\r\n\r\n\r\nThe str.rstrip() function solves this.\r\n\r\nsuggestion\r\n x = x.rstrip('/')\r\n if x in ignored_links:\r\n continue\r\n\r\n if x not in seen:\r\n seen[x] = 1\r\n else:\r\n if seen[x] == 1:\r\n dupes.append(x)\r\n\n\n@author:\n@user1 Thanks for reviewing my PR and spotting an extra check with / character.", "path": "build/validate_links.py", "diff_hunk": "@@ -16,6 +21,29 @@ def parse_links(filename):\n links = [raw_link[0] for raw_link in raw_links]\n return links\n \n+def dup_links(links):\n+ """Check for duplicated links"""\n+ print(f'Checking for duplicated links...')\n+ hasError = False\n+ seen = {}\n+ dupes = []\n+\n+ for x in links:\n+ if x in ignored_links:\n+ continue\n+\n+ if x not in seen:\n+ seen[x] = 1\n+ else:\n+ if seen[x] == 1:\n+ dupes.append(x)", "line": null, "start_line": null, "original_line": 39, "original_start_line": 32}], "merged_commit": "ed25ea30ac9ada949d553326576cd2b4b6b2f751", "merged_patch": "diff --git a/build/validate_format.py b/build/validate_format.py\nindex 22fca30a2d..545fea2c9a 100755\n--- a/build/validate_format.py\n+++ b/build/validate_format.py\n@@ -20,7 +20,6 @@\n \n errors = []\n title_links = []\n-previous_links = []\n anchor_re = re.compile(anchor + '\s(.+)')\n section_title_re = re.compile('\\s\[(.)\]')\n link_re = re.compile('\[(.+)\]\((http.*)\)')\n@@ -68,12 +67,6 @@ def check_entry(line_num, segments):\n title = title_re_match.group(1)\n if title.upper().endswith(' API'):\n add_error(line_num, 'Title should not end with "... API". Every entry is an API here!')\n- # do not allow duplicate links\n- link = title_re_match.group(2)\n- if link in previous_links:\n- add_error(line_num, 'Duplicate link - entries should only be included in one section')\n- else:\n- previous_links.append(link)\n # END Title\n # START Description\n # first character should be capitalized\ndiff --git a/build/validate_links.py b/build/validate_links.py\nindex ab36b0c840..eb5dfa308e 100755\n--- a/build/validate_links.py\n+++ b/build/validate_links.py\n@@ -5,6 +5,12 @@\n import socket\n import sys\n \n+ignored_links = [\n+ 'https://github.com/public-apis/public-apis/actions?query=workflow%3A%22Run+tests%22', \n+ 'https://github.com/public-apis/public-apis/workflows/Validate%20links/badge.svg?branch=master', \n+ 'https://github.com/public-apis/public-apis/actions?query=workflow%3A%22Validate+links%22',\n+ 'https://github.com/davemachado/public-api',\n+]\n \n def parse_links(filename):\n """Returns a list of URLs from text file"""\n@@ -16,6 +22,30 @@ def parse_links(filename):\n links = [raw_link[0] for raw_link in raw_links]\n return links\n \n+def dup_links(links):\n+ """Check for duplicated links"""\n+ print(f'Checking for duplicated links...')\n+ hasError = False\n+ seen = {}\n+ dupes = []\n+\n+ for link in links:\n+ link = link.rstrip('/')\n+ if link in ignored_links:\n+ continue\n+\n+ if link not in seen:\n+ seen[link] = 1\n+ else:\n+ if seen[link] == 1:\n+ dupes.append(link)\n+\n+ if not dupes:\n+ print(f"No duplicate links")\n+ else:\n+ print(f"Found duplicate links: {dupes}") \n+ hasError = True \n+ return hasError\n \n def validate_links(links):\n """Checks each entry in JSON file for live link"""\n@@ -58,6 +88,9 @@ def validate_links(links):\n if num_args < 2:\n print("No .md file passed")\n sys.exit(1)\n- hasError = validate_links(parse_links(sys.argv[1]))\n+ links = parse_links(sys.argv[1])\n+ hasError = dup_links(links)\n+ if not hasError:\n+ hasError = validate_links(links)\n if hasError:\n sys.exit(1)\n", "metadata": {"problem_domain": "Bug Fixes", "difficulty": "medium", "estimated_review_effort": 3}}

[SeasonPilot]

{"instance_id": "emcie-co__parlant-619@a0ac66b", "repo": "emcie-co/parlant", "language": "Python", "pull_number": 619, "title": "Add OpenRouter integration and direct model_name configuration for NLP services (#618)", "body": "### Summary\r\nThis PR introduces native OpenRouter integration for NLP services and adds support for direct model_name configuration.\r\n\r\n### Details\r\n- Integrated OpenRouter as a new NLP service provider.\r\n- Enabled direct model_name configuration for flexible model selection.\r\n- Supports access to 400+ LLMs via OpenRouter.\r\n- Updated configuration logic and examples to reflect the new feature.\r\n- Ensured backward compatibility with existing embedder configurations.\r\n\r\n### Related Issue\r\nCloses #618 \u2014 [Enhancement] Add Direct model_name Configuration & Native OpenRouter Integration (Access 400+ LLMs)\r\n\r\n### Type of Change\r\n- [x] \u2728 Enhancement (new feature or improvement)\r\n- [ ] \ud83d\udc1e Bug fix\r\n- [ ] \ud83e\udde9 Refactor\r\n- [ ] \ud83d\udcda Documentation update\r\n\r\n### Testing\r\n- Verified OpenRouter API connectivity with multiple model names (including DeepSeek).\r\n- Confirmed logger and meter are passed correctly to JinaAIEmbedder.\r\n- Tested fallback logic for non-OpenRouter configurations.\r\n- End-to-end tested NLP service initialization and embeddings generation.\r\n\r\n### Additional Notes\r\nThis enhancement expands the flexibility of NLP service integrations, allowing developers to seamlessly leverage multiple models from OpenRouter with simple configuration changes.\r\n", "created_at": "2025-10-28T11:27:07Z", "problem_statement": "[Enhancement] Add Direct model_name Configuration & Native OpenRouter Integration (Access 400+ LLMs)\n# Motivation\nCurrently, Parlant requires setting the model_name for NLP services exclusively through environment variables. \nWhile this approach works, it limits flexibility and slows down experimentation \u2014 especially for developers who need to dynamically switch models, run multi-provider setups, or test various configurations programmatically. \n\nThis makes workflows cumbersome, particularly when managing different model providers or experimenting with new LLMs during development.\n\n---\n\n# Solution Proposal\nIntroduce two key backend enhancements to improve flexibility and scalability:\n\n### 1. Direct model_name Configuration in Code\nAllow specifying the model name directly during NLP service initialization (while keeping environment variables as a fallback for backward compatibility).\n\nBefore:\npython\nnlp_service = NLPServices.deepseek\n\n\nAfter:\npython\nnlp_service = NLPServices.openrouter(\n model_name=\"deepseek/deepseek-chat-v3.1\", # The Model name \n max_tokens=131072 #The context window of the model \n\n\nThis change enables per-instance customization, making it easy to test and switch between models without modifying environment settings.\n\n---\n\n### 2. Native OpenRouter Integration\nAdd native OpenRouter service support to Parlant, unlocking access to over 400+ LLMs from top providers such as OpenAI, Anthropic, Mistral, Google, and many more \u2014 all through a single unified API layer.\n\nBenefits:\n- Access to 400+ models from multiple providers via OpenRouter \n- Unified interface for all supported NLP providers \n- Dynamic runtime configuration and rapid experimentation \n- Fully compatible with existing Parlant service architecture \n\n---\n\n# Discussion\nI\u2019ve already implemented and tested the OpenRouter service integration, which supports direct model configuration as shown above. \n\nIf this aligns with the maintainers\u2019 roadmap, I\u2019d be happy to contribute the backend implementation through a pull request, including:\n- In-code model_name parameter support \n- Full OpenRouter backend integration \n\nThis enhancement would greatly improve Parlant\u2019s flexibility, making it more developer-friendly and future-proof for large-scale multi-model deployments.", "hints_text": "OpenRouter has effectively addressed a major challenge for developers by simplifying the management of over 400 different models from various providers with just a simple name change.\n\nThis will be a really game-changer!\n\n\nHey @mc-dorzo \ud83d\udc4b\n\nI\u2019ve created the PR for the OpenRouter integration and direct model_name configuration \u2014 and I\u2019ve tested everything thoroughly.\nAll features are working perfectly on my end \u2705\n\nYou can go ahead and merge it, or feel free to test it yourself if you\u2019d like before merging.\n\nThanks! \ud83d\ude80\n\nExample code:\n\n\n\nasync with p.Server(\n nlp_service=NLPServices.openrouter(\n model_name=\"openai/gpt-4o-mini\", # Specify your desired model\n max_tokens=128000 # Define model context window\n )\n) as server:\n \n agent = await server.create_agent(\n name=\"Abroad Inquiry Agent\",\n description=\"An expert abroad education consultant at Abroad Inquiry.\"\n )\n\n\nHey @kichanyurd \ud83d\udc4b\n\nI\u2019ve created the PR for the OpenRouter integration and direct model_name configuration \u2014 and I\u2019ve tested everything thoroughly.\nAll features are working perfectly on my end \u2705\n\nYou can go ahead and merge it, or feel free to test it yourself if you\u2019d like before merging.\n\nThanks! \ud83d\ude80", "resolved_issues": [{"number": 618, "title": "[Enhancement] Add Direct model_name Configuration & Native OpenRouter Integration (Access 400+ LLMs)", "body": "# Motivation\nCurrently, Parlant requires setting the model_name for NLP services exclusively through environment variables. \nWhile this approach works, it limits flexibility and slows down experimentation \u2014 especially for developers who need to dynamically switch models, run multi-provider setups, or test various configurations programmatically. \n\nThis makes workflows cumbersome, particularly when managing different model providers or experimenting with new LLMs during development.\n\n---\n\n# Solution Proposal\nIntroduce two key backend enhancements to improve flexibility and scalability:\n\n### 1. Direct model_name Configuration in Code\nAllow specifying the model name directly during NLP service initialization (while keeping environment variables as a fallback for backward compatibility).\n\nBefore:\npython\nnlp_service = NLPServices.deepseek\n\n\nAfter:\npython\nnlp_service = NLPServices.openrouter(\n model_name=\"deepseek/deepseek-chat-v3.1\", # The Model name \n max_tokens=131072 #The context window of the model \n\n\nThis change enables per-instance customization, making it easy to test and switch between models without modifying environment settings.\n\n---\n\n### 2. Native OpenRouter Integration\nAdd native OpenRouter service support to Parlant, unlocking access to over 400+ LLMs from top providers such as OpenAI, Anthropic, Mistral, Google, and many more \u2014 all through a single unified API layer.\n\nBenefits:\n- Access to 400+ models from multiple providers via OpenRouter \n- Unified interface for all supported NLP providers \n- Dynamic runtime configuration and rapid experimentation \n- Fully compatible with existing Parlant service architecture \n\n---\n\n# Discussion\nI\u2019ve already implemented and tested the OpenRouter service integration, which supports direct model configuration as shown above. \n\nIf this aligns with the maintainers\u2019 roadmap, I\u2019d be happy to contribute the backend implementation through a pull request, including:\n- In-code model_name parameter support \n- Full OpenRouter backend integration \n\nThis enhancement would greatly improve Parlant\u2019s flexibility, making it more developer-friendly and future-proof for large-scale multi-model deployments.\n"}], "base_commit": "f44fb08f4e1a8b126885b1226099c6e8a5d92b3c", "commit_to_review": {"head_commit": "a0ac66b4fe019c2109e8f7b7c9189ee608bd2d87", "head_commit_message": "docs: Enhance OpenRouter documentation with embedding model support\n\n- Add comprehensive embedder_model_name parameter documentation\n- Document all embedding models and their dimensions\n- Add dimension detection and override mechanisms\n- Include troubleshooting for dimension mismatch errors\n- Add multiple usage examples with different configurations\n- Expand configuration options and best practices\n- Add complete production-ready example\n- Improve readability and organization\n\nSigned-off-by: Sifat Hasan sihabhossan633@gmail.com", "patch_to_review": "diff --git a/docs/adapters/nlp/openrouter.md b/docs/adapters/nlp/openrouter.md\nnew file mode 100644\nindex 000000000..45d821d8b\n--- /dev/null\n+++ b/docs/adapters/nlp/openrouter.md\n@@ -0,0 +1,599 @@\n+# OpenRouter Service Documentation\n+\n+The OpenRouter service provides access to 400+ AI models through a single unified API, including GPT-4, Claude, Llama, Qwen, and many more. OpenRouter makes it easy to switch between different models for both text generation and embeddings without changing code.\n+\n+## Prerequisites\n+\n+1. OpenRouter Account: Sign up at openrouter.ai\n+2. API Key: Get your API key from the OpenRouter dashboard\n+3. Model Access: Ensure you have access to the models you want to use\n+\n+## Quick Start\n+\n+### Basic Setup\n+\n+bash\n+# Set your OpenRouter API key (required)\n+export OPENROUTER_API_KEY=\"your-api-key-here\"\n+\n+# Optionally set default models\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-large\"\n+\n+\n+### Minimal Example\n+\n+python\n+import parlant.sdk as p\n+from parlant.sdk import NLPServices\n+\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"AI Assistant\",\n+ description=\"A helpful assistant powered by OpenRouter.\",\n+ )\n+ # \ud83c\udf89 Ready to use at http://localhost:8800\n+\n+\n+## Configuration Options\n+\n+### Direct Configuration\n+\n+Configure models directly in code for maximum flexibility:\n+\n+python\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"openai/gpt-4o-mini\", # LLM model name\n+ embedder_model_name=\"openai/text-embedding-3-large\", # Embedding model name\n+ max_tokens=128000 # Model context length\n+ )\n+) as server:\n+ # Your agent code here\n+ pass\n+\n+\n+### Environment-Based Configuration\n+\n+Use environment variables for configuration:\n+\n+bash\n+# LLM Configuration\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_MAX_TOKENS=\"128000\"\n+\n+# Embedding Configuration\n+export OPENROUTER_EMBEDDER_MODEL=\"qwen/qwen3-embedding-8b\"\n+export OPENROUTER_EMBEDDER_DIMENSIONS=\"4096\" # Optional override\n+\n+# Analytics (optional)\n+export OPENROUTER_HTTP_REFERER=\"https://myapp.com\"\n+export OPENROUTER_SITE_NAME=\"My Application\"\n+\n+\n+### Mixed Configuration\n+\n+Combine environment variables and code for flexible setup:\n+\n+python\n+# Uses OPENROUTER_MODEL from environment\n+# But overrides embedder_model_name in code\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ embedder_model_name=\"qwen/qwen3-embedding-8b\"\n+ )\n+) as server:\n+ pass\n+\n+\n+## Environment Variables Reference\n+\n+### Required Variables\n+\n+| Variable | Description | Example |\n+|----------|-------------|---------|\n+| OPENROUTER_API_KEY | Your OpenRouter API key | sk-or-v1-... |\n+\n+### Optional Variables - LLM Configuration\n+\n+| Variable | Description | Default | Example |\n+|----------|-------------|---------|---------|\n+| OPENROUTER_MODEL | LLM model name | openai/gpt-4o | openai/gpt-4o-mini |\n+| OPENROUTER_MAX_TOKENS | Max tokens limit | Auto-detected | 128000 |\n+\n+### Optional Variables - Embedding Configuration\n+\n+| Variable | Description | Default | Example |\n+|----------|-------------|---------|---------|\n+| OPENROUTER_EMBEDDER_MODEL | Embedding model name | openai/text-embedding-3-large | qwen/qwen3-embedding-8b |\n+| OPENROUTER_EMBEDDER_DIMENSIONS | Override embedding dimensions | Auto-detected | 4096 |\n+\n+### Optional Variables - Analytics\n+\n+| Variable | Description | Example |\n+|----------|-------------|---------|\n+| OPENROUTER_HTTP_REFERER | Your app's URL (for analytics) | https://myapp.com |\n+| OPENROUTER_SITE_NAME | Your app's name (for analytics) | My Application |\n+\n+## Supported Models\n+\n+OpenRouter supports 400+ models from different providers. Models are automatically optimized with specialized configurations when available.\n+\n+### Pre-configured LLM Models\n+\n+These models have specialized configurations for optimal performance:\n+\n+| Model | Provider | Context | Use Case |\n+|-------|----------|---------|----------|\n+| openai/gpt-4o | OpenAI | 128K | Default, best overall quality |\n+| openai/gpt-4o-mini | OpenAI | 128K | Cost-effective, fast |\n+| anthropic/claude-3.5-sonnet | Anthropic | 200K | Advanced reasoning, long context |\n+| meta-llama/llama-3.3-70b-instruct | Meta | 8K | Open-source option |\n+\n+### Supported Embedding Models\n+\n+The service supports multiple embedding models with automatic dimension detection:\n+\n+| Model | Dimensions | Provider | Use Case |\n+|-------|------------|----------|----------|\n+| openai/text-embedding-3-large | 3072 | OpenAI | Default, high quality |\n+| openai/text-embedding-3-small | 1536 | OpenAI | Faster, smaller |\n+| openai/text-embedding-ada-002 | 1536 | OpenAI | Legacy model |\n+| qwen/qwen3-embedding-8b | 4096 | Qwen | High dimension, multilingual |\n+| qwen/qwen-embedding-v2 | 1536 | Qwen | Multilingual embeddings |\n+\n+### Using Any OpenRouter Model\n+\n+You can use any model that OpenRouter supports:\n+\n+python\n+# LLM Models\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"google/gemini-pro-1.5\"\n+ )\n+) as server:\n+ pass\n+\n+# Embedding Models\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"openai/gpt-4o-mini\",\n+ embedder_model_name=\"qwen/qwen3-embedding-8b\"\n+ )\n+) as server:\n+ pass\n+\n+\n+Check the OpenRouter Models page for the full list of available models.\n+\n+## Usage Examples\n+\n+### Example 1: Default Configuration\n+\n+Use the default models (GPT-4o for LLM, text-embedding-3-large for embeddings):\n+\n+python\n+import parlant.sdk as p\n+from parlant.sdk import NLPServices\n+\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"General Assistant\",\n+ description=\"A helpful AI assistant.\"\n+ )\n+\n+\n+### Example 2: Custom LLM Model\n+\n+Use Claude for text generation:\n+\n+python\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"anthropic/claude-3.5-sonnet\"\n+ )\n+) as server:\n+ agent = await server.create_agent(\n+ name=\"Claude Assistant\",\n+ description=\"Powered by Claude.\"\n+ )\n+\n+\n+### Example 3: Custom Embedder Model\n+\n+Use a custom embedding model for better multilingual support:\n+\n+python\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"openai/gpt-4o-mini\",\n+ embedder_model_name=\"qwen/qwen3-embedding-8b\"\n+ )\n+) as server:\n+ agent = await server.create_agent(\n+ name=\"Multilingual Assistant\",\n+ description=\"Supports multiple languages.\"\n+ )\n+\n+\n+### Example 4: High-Performance Setup\n+\n+Optimize for speed and quality:\n+\n+python\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"openai/gpt-4o-mini\",\n+ embedder_model_name=\"openai/text-embedding-3-large\",\n+ max_tokens=128000\n+ )\n+) as server:\n+ agent = await server.create_agent(\n+ name=\"High-Performance Agent\",\n+ description=\"Optimized for speed and accuracy.\"\n+ )\n+\n+\n+### Example 5: Cost-Optimized Setup\n+\n+Balance quality and cost:\n+\n+python\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"openai/gpt-4o-mini\",\n+ embedder_model_name=\"openai/text-embedding-3-small\"\n+ )\n+) as server:\n+ agent = await server.create_agent(\n+ name=\"Cost-Optimized Agent\",\n+ description=\"Optimized for cost-effectiveness.\"\n+ )\n+\n+\n+## Embedding Model Configuration\n+\n+### Understanding Embedding Dimensions\n+\n+Different embedding models produce vectors of different dimensions. The service automatically detects dimensions for known models, and can auto-detect from API responses for unknown models.\n+\n+### Known Embedding Dimensions\n+\n+The following models have pre-configured dimensions:\n+\n+- openai/text-embedding-3-large: 3072 dimensions\n+- openai/text-embedding-3-small: 1536 dimensions\n+- openai/text-embedding-ada-002: 1536 dimensions\n+- qwen/qwen3-embedding-8b: 4096 dimensions\n+- qwen/qwen-embedding-v2: 1536 dimensions\n+\n+### Auto-Detection\n+\n+For unknown models, dimensions are automatically detected from the first API response and cached for subsequent use.\n+\n+### Manual Dimension Override\n+\n+If needed, you can manually specify dimensions via environment variable:\n+\n+bash\n+export OPENROUTER_EMBEDDER_DIMENSIONS=\"4096\"\n+\n+\n+\u26a0\ufe0f Important: If you change embedder models or dimensions, you may need to clear your vector database cache to avoid dimension mismatch errors.\n+\n+## Dynamic Model Selection\n+\n+OpenRouter intelligently handles model selection and configuration:\n+\n+### Automatic Generator Selection\n+\n+Known models use specialized generators for optimal performance:\n+\n+- openai/gpt-4o \u2192 OpenRouterGPT4O\n+- openai/gpt-4o-mini \u2192 OpenRouterGPT4OMini\n+- anthropic/claude-3.5-sonnet \u2192 OpenRouterClaude35Sonnet\n+- meta-llama/llama-3.3-70b-instruct \u2192 OpenRouterLlama33_70B\n+- Other models \u2192 Dynamic generator with auto-configured parameters\n+\n+### Automatic Embedder Selection\n+\n+Embedders are automatically configured based on the model name:\n+\n+- Known models \u2192 Pre-configured dimensions\n+- Unknown models \u2192 Auto-detected dimensions from API response\n+- Dynamic embedder \u2192 Created with proper container resolution\n+\n+## Advantages of OpenRouter\n+\n+1. Model Diversity: Access to 400+ models from different providers\n+2. Unified Embeddings: Native support for embedding models via the same API\n+3. Cost Flexibility: Choose models based on price-performance needs\n+4. Single API: One integration for multiple providers\n+5. Auto-Optimization: Automatic configuration for known models\n+6. Flexible Configuration: Mix environment variables and code configuration\n+7. Analytics: Built-in usage tracking through OpenRouter dashboard\n+\n+## Troubleshooting\n+\n+### Rate Limit Errors\n+\n+Error:\n+\n+OpenRouter API rate limit exceeded\n+\n+\n+Solutions:\n+- Check your OpenRouter account balance and billing status\n+- Review usage limits in the OpenRouter dashboard\n+- Consider upgrading your plan for higher limits\n+- Try a different model with higher rate limits\n+- Wait a moment before retrying\n+\n+### JSON Mode Not Supported\n+\n+Error:\n+\n+Model 'xyz' does not support JSON mode\n+\n+\n+Solutions:\n+- OpenRouter automatically falls back to prompting for JSON output\n+- Consider using a model that supports JSON mode:\n+ - openai/gpt-4o\n+ - openai/gpt-4o-mini\n+ - anthropic/claude-3.5-sonnet\n+- The fallback still produces structured output reliably\n+\n+### Dimension Mismatch Errors\n+\n+Error:\n+\n+ValueError: all the input array dimensions except for the concatenation axis must match exactly\n+\n+\n+Solutions:\n+- This occurs when switching embedder models with different dimensions\n+- Clear your vector database cache/embeddings\n+- Or delete the cached embeddings files in your parlant-data directory\n+- The embedder will create new embeddings with the correct dimensions\n+\n+### Authentication Errors\n+\n+Error:\n+\n+OPENROUTER_API_KEY is not set\n+\n+\n+Solutions:\n+- Set the OPENROUTER_API_KEY environment variable\n+- Verify your API key in the OpenRouter dashboard\n+- Ensure the key hasn't expired or been revoked\n+- Check for typos in the environment variable name\n+\n+### Container Resolution Errors\n+\n+Error:\n+\n+Unable to construct dependency of type OpenRouterEmbedder\n+\n+\n+Solutions:\n+- This is automatically handled by the dynamic embedder class\n+- Ensure you're using the latest version of the code\n+- If the error persists, check that embedder_model_name is correctly set\n+\n+## Cost Management\n+\n+OpenRouter provides transparent pricing across models. Choose models based on your needs:\n+\n+### Cost-Effective LLM Options\n+\n+python\n+# GPT-4o-mini - Good quality, lower cost\n+model_name=\"openai/gpt-4o-mini\"\n+\n+# Claude Haiku - Fast, affordable\n+model_name=\"anthropic/claude-3-haiku\"\n+\n+# Llama - Open source, very affordable\n+model_name=\"meta-llama/llama-3.3-70b-instruct\"\n+\n+\n+### Cost-Effective Embedding Options\n+\n+python\n+# text-embedding-3-small - Smaller, faster, cheaper\n+embedder_model_name=\"openai/text-embedding-3-small\"\n+\n+# text-embedding-ada-002 - Legacy, very affordable\n+embedder_model_name=\"openai/text-embedding-ada-002\"\n+\n+\n+### Premium Options\n+\n+python\n+# GPT-4o - Highest quality\n+model_name=\"openai/gpt-4o\"\n+\n+# text-embedding-3-large - Highest quality embeddings\n+embedder_model_name=\"openai/text-embedding-3-large\"\n+\n+\n+Check OpenRouter pricing for current rates.\n+\n+## Model Selection Guide\n+\n+### When to Use Each LLM Model\n+\n+GPT-4o (openai/gpt-4o)\n+- Complex reasoning tasks\n+- Code generation and debugging\n+- Multi-step problem solving\n+- When accuracy is critical\n+- Best overall performance\n+\n+GPT-4o-mini (openai/gpt-4o-mini)\n+- General purpose tasks\n+- High-volume applications\n+- Cost-sensitive use cases\n+- When 95% accuracy is sufficient\n+- Fast response times\n+\n+Claude (anthropic/claude-3.5-sonnet)\n+- Long context tasks (200K tokens)\n+- Creative writing\n+- Detailed analysis\n+- When you need extended reasoning\n+- Complex document understanding\n+\n+Llama (meta-llama/llama-3.3-70b-instruct)\n+- Open-source requirements\n+- Custom fine-tuning needs\n+- Privacy-sensitive applications\n+- Cost optimization\n+- Self-hosted deployments\n+\n+### When to Use Each Embedding Model\n+\n+text-embedding-3-large (openai/text-embedding-3-large)\n+- Default choice for most use cases\n+- High quality semantic search\n+- Best accuracy for retrieval\n+- Recommended for production\n+\n+text-embedding-3-small (openai/text-embedding-3-small)\n+- Cost-sensitive applications\n+- Faster embedding generation\n+- Good quality for most tasks\n+- Large-scale deployments\n+\n+qwen3-embedding-8b (qwen/qwen3-embedding-8b)\n+- Multilingual applications\n+- Higher dimensional space (4096)\n+- Better fine-grained distinctions\n+- When you need more embedding dimensions\n+\n+## Best Practices\n+\n+### 1. Start with Defaults\n+Begin with the default models (gpt-4o and text-embedding-3-large) for best balance of quality and performance.\n+\n+### 2. Use Mini for Scale\n+Switch to gpt-4o-mini for high-volume operations where cost is a concern.\n+\n+### 3. Match Embedder to Use Case\n+- Use text-embedding-3-large for quality-critical applications\n+- Use text-embedding-3-small for cost-sensitive deployments\n+- Use qwen3-embedding-8b for multilingual or high-dimensional needs\n+\n+### 4. Set Max Tokens\n+Prevent runaway costs by setting appropriate max_tokens limits:\n+\n+python\n+max_tokens=128000 # For long-context models\n+max_tokens=8192 # For standard use cases\n+\n+\n+### 5. Monitor Costs\n+Regularly check the OpenRouter dashboard to monitor usage and costs.\n+\n+### 6. Use Analytics\n+Set OPENROUTER_HTTP_REFERER and OPENROUTER_SITE_NAME to track usage across different applications.\n+\n+### 7. Clear Cache When Changing Models\n+If you switch embedder models, clear your vector database cache to avoid dimension mismatches.\n+\n+### 8. Environment Variables for Production\n+Use environment variables for production deployments instead of hardcoding values:\n+\n+bash\n+# Production configuration\n+export OPENROUTER_API_KEY=\"sk-or-v1-...\"\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-large\"\n+\n+\n+## Advanced Configuration\n+\n+### Custom Dimensions for Unknown Models\n+\n+If using an embedding model not in the known list, you can specify dimensions:\n+\n+bash\n+export OPENROUTER_EMBEDDER_MODEL=\"custom/embedding-model\"\n+export OPENROUTER_EMBEDDER_DIMENSIONS=\"2048\"\n+\n+\n+The service will also auto-detect dimensions from the first API response.\n+\n+### Combining Multiple Configurations\n+\n+You can mix different configuration methods:\n+\n+python\n+# Environment variables provide defaults\n+# Code overrides specific values\n+async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"anthropic/claude-3.5-sonnet\", # Override env var\n+ max_tokens=200000 # Override env var\n+ # embedder_model_name uses OPENROUTER_EMBEDDER_MODEL from env\n+ )\n+) as server:\n+ pass\n+\n+\n+## Additional Resources\n+\n+- OpenRouter Documentation\n+- Available Models\n+- API Reference\n+- Pricing Information\n+- Rate Limits\n+\n+## Example: Complete Setup\n+\n+Here's a complete example showing a production-ready setup:\n+\n+python\n+import parlant.sdk as p\n+from parlant.sdk import NLPServices\n+\n+@p.tool\n+async def get_weather(context: p.ToolContext, city: str) -> p.ToolResult:\n+ # Your weather API logic here\n+ return p.ToolResult(f\"Sunny, 72\u00b0F in {city}\")\n+\n+async def main():\n+ async with p.Server(\n+ nlp_service=NLPServices.openrouter(\n+ model_name=\"openai/gpt-4o-mini\",\n+ embedder_model_name=\"openai/text-embedding-3-large\",\n+ max_tokens=32768\n+ )\n+ ) as server:\n+ agent = await server.create_agent(\n+ name=\"Weather Assistant\",\n+ description=\"Helps users check weather conditions.\"\n+ )\n+ \n+ await agent.create_guideline(\n+ condition=\"User asks about weather\",\n+ action=\"Get weather information using the get_weather tool\",\n+ tools=[get_weather]\n+ )\n+ \n+ # \ud83c\udf89 Ready at http://localhost:8800\n+\n+if __name__ == \"__main__\":\n+ import asyncio\n+ asyncio.run(main())\n+\n+\n+This setup provides:\n+- \u2705 Cost-effective LLM (gpt-4o-mini)\n+- \u2705 High-quality embeddings (text-embedding-3-large)\n+- \u2705 Reasonable token limit (32K)\n+- \u2705 Tool integration\n+- \u2705 Guideline-based behavior control\ndiff --git a/src/parlant/adapters/nlp/openrouter_service.py b/src/parlant/adapters/nlp/openrouter_service.py\nnew file mode 100644\nindex 000000000..b99fdd4db\n--- /dev/null\n+++ b/src/parlant/adapters/nlp/openrouter_service.py\n@@ -0,0 +1,592 @@\n+# Copyright 2025 Emcie Co Ltd.\n+#\n+# Licensed under the Apache License, Version 2.0 (the "License");\n+# you may not use this file except in compliance with the License.\n+# You may obtain a copy of the License at\n+#\n+# http://www.apache.org/licenses/LICENSE-2.0\n+#\n+# Unless required by applicable law or agreed to in writing, software\n+# distributed under the License is distributed on an "AS IS" BASIS,\n+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n+# See the License for the specific language governing permissions and\n+# limitations under the License.\n+\n+from future import annotations\n+import time\n+from openai import (\n+ APIConnectionError,\n+ APIResponseValidationError,\n+ APITimeoutError,\n+ AsyncClient,\n+ BadRequestError,\n+ ConflictError,\n+ InternalServerError,\n+ RateLimitError,\n+)\n+from typing import Any, Callable, Mapping\n+from typing_extensions import override\n+import json\n+import jsonfinder # type: ignore\n+import os\n+\n+from pydantic import ValidationError\n+import tiktoken\n+\n+from parlant.adapters.nlp.common import normalize_json_output\n+from parlant.core.engines.alpha.prompt_builder import PromptBuilder\n+from parlant.core.loggers import Logger\n+from parlant.core.meter import Meter\n+from parlant.core.nlp.policies import policy, retry\n+from parlant.core.nlp.tokenization import EstimatingTokenizer\n+from parlant.core.nlp.service import NLPService\n+from parlant.core.nlp.embedding import BaseEmbedder, Embedder, EmbeddingResult\n+from parlant.core.nlp.generation import (\n+ T,\n+ BaseSchematicGenerator,\n+ SchematicGenerationResult,\n+)\n+from parlant.core.nlp.generation_info import GenerationInfo, UsageInfo\n+from parlant.core.nlp.moderation import (\n+ ModerationService,\n+ NoModeration,\n+)\n+\n+RATE_LIMIT_ERROR_MESSAGE = """\\n+OpenRouter API rate limit exceeded. Possible reasons:\n+1. Your account may have insufficient API credits.\n+2. You may be using a free-tier account with limited request capacity.\n+3. You might have exceeded the requests-per-minute limit for your account.\n+\n+Recommended actions:\n+- Check your OpenRouter account balance and billing status.\n+- Review your API usage limits in OpenRouter's dashboard.\n+- For more details on rate limits and usage tiers, visit:\n+ https://openrouter.ai/docs/api-reference/limits\n+\"\"\"\n+\n+\n+class OpenRouterEstimatingTokenizer(EstimatingTokenizer):\n+ def init(self, model_name: str) -> None:\n+ self.model_name = model_name\n+ # Use gpt-4 encoding as default for token estimation\n+ self.encoding = tiktoken.encoding_for_model("gpt-4o-2024-08-06")\n+\n+ @OverRide\n+ async def estimate_token_count(self, prompt: str) -> int:\n+ tokens = self.encoding.encode(prompt)\n+ return len(tokens)\n+\n+\n+class OpenRouterSchematicGenerator(BaseSchematicGenerator[T]):\n+ supported_openrouter_params = ["temperature", "max_tokens"]\n+\n+ def init(\n+ self,\n+ model_name: str,\n+ logger: Logger,\n+ meter: Meter,\n+ ) -> None:\n+ super().init(logger=logger, meter=meter, model_name=model_name)\n+ self._logger = logger\n+\n+ # Build extra headers from environment variables\n+ extra_headers = {}\n+ if "OPENROUTER_HTTP_REFERER" in os.environ:\n+ extra_headers["HTTP-Referer"] = os.environ["OPENROUTER_HTTP_REFERER"]\n+ if "OPENROUTER_SITE_NAME" in os.environ:\n+ extra_headers["X-Title"] = os.environ["OPENROUTER_SITE_NAME"]\n+\n+ self._client = AsyncClient(\n+ base_url="https://openrouter.ai/api/v1\",\n+ api_key=os.environ["OPENROUTER_API_KEY"],\n+ default_headers=extra_headers if extra_headers else None,\n+ )\n+\n+ self._tokenizer = OpenRouterEstimatingTokenizer(model_name=self.model_name)\n+\n+ @Property \n+ @OverRide\n+ def id(self) -> str:\n+ return f"openrouter/{self.model_name}"\n+\n+ @Property\n+ @OverRide\n+ def tokenizer(self) -> OpenRouterEstimatingTokenizer:\n+ return self._tokenizer\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ # Default implementation - should be overridden by subclasses\n+ return 8192\n+\n+ @Policy(\n+ [\n+ retry(\n+ exceptions=(\n+ APIConnectionError,\n+ APITimeoutError,\n+ ConflictError,\n+ RateLimitError,\n+ APIResponseValidationError,\n+ ),\n+ ),\n+ retry(InternalServerError, max_exceptions=2, wait_times=(1.0, 5.0)),\n+ ]\n+ )\n+ @OverRide\n+ async def do_generate(\n+ self,\n+ prompt: str | PromptBuilder,\n+ hints: Mapping[str, Any] = {},\n+ ) -> SchematicGenerationResult[T]:\n+ if isinstance(prompt, PromptBuilder):\n+ prompt = prompt.build()\n+\n+ openrouter_api_arguments = {\n+ k: v for k, v in hints.items() if k in self.supported_openrouter_params\n+ }\n+\n+ t_start = time.time()\n+ \n+ # Try with JSON mode first, but catch errors gracefully\n+ response = None\n+ \n+ try:\n+ # Try with JSON mode\n+ response = await self._client.chat.completions.create(\n+ messages=[{"role": "user", "content": prompt}],\n+ model=self.model_name,\n+ response_format={"type": "json_object"},\n+ **openrouter_api_arguments,\n+ )\n+ except BadRequestError as e:\n+ # Check if it's a JSON mode error\n+ error_str = str(e)\n+ if "JSON mode" in error_str or "json_object" in error_str.lower():\n+ self._logger.error(\n+ f"\n\u26a0\ufe0f Model '{self.model_name}' does not support JSON mode.\n"\n+ f"Please switch to a model that supports JSON mode (e.g., 'openai/gpt-4o', 'anthropic/claude-3.5-sonnet').\n"\n+ f"Attempting to continue without JSON mode enforcement, but results may be less reliable.\n"\n+ )\n+ # Retry without JSON mode with a system message to instruct JSON output\n+ try:\n+ # Add system message to instruct the model to output JSON\n+ json_instruction = "IMPORTANT: You must respond with ONLY valid JSON. No explanatory text before or after the JSON. The response must be a valid JSON object."\n+ response = await self._client.chat.completions.create(\n+ messages=[\n+ {"role": "system", "content": json_instruction},\n+ {"role": "user", "content": prompt}\n+ ],\n+ model=self.model_name,\n+ **openrouter_api_arguments,\n+ )\n+ except Exception as retry_error:\n+ self._logger.error(\n+ f"\n\u274c Failed to use model '{self.model_name}' even without JSON mode.\n"\n+ f"Error: {retry_error}\n"\n+ f"Please change your model to one that supports JSON mode or use a different model entirely.\n"\n+ )\n+ raise\n+ else:\n+ # Some other BadRequest error - just log it once and raise\n+ self._logger.error(f"OpenRouter API BadRequest: {e}")\n+ raise\n+ except RateLimitError as e:\n+ self._logger.error(\n+ f"\n\u23f1\ufe0f Rate limit exceeded for model '{self.model_name}'.\n"\n+ f"{RATE_LIMIT_ERROR_MESSAGE}\n"\n+ f"Consider:\n"\n+ f" - Using a different model\n"\n+ f" - Waiting a moment before retrying\n"\n+ f" - Adding your own API key for higher limits\n"\n+ )\n+ raise\n+ except Exception as e:\n+ self._logger.error(\n+ f"\n\u274c OpenRouter API error with model '{self.model_name}': {type(e).name}\n"\n+ f"{e}\n"\n+ f"Consider switching to a more compatible model.\n"\n+ )\n+ raise\n+ \n+ t_end = time.time()\n+\n+ if response.usage:\n+ self._logger.trace(response.usage.model_dump_json(indent=2))\n+\n+ raw_content = response.choices[0].message.content or "{}"\n+ \n+ # Check if we got empty response\n+ if not raw_content.strip() or raw_content.strip() == "{}":\n+ self._logger.error(\n+ f"\n\u274c Model '{self.model_name}' returned empty or invalid JSON.\n"\n+ f"Response: {raw_content}\n"\n+ f"This model may not be compatible with structured output requirements.\n"\n+ f"Please switch to a model that supports JSON mode (e.g., 'openai/gpt-4o', 'anthropic/claude-3.5-sonnet').\n"\n+ )\n+ # Set empty JSON as fallback\n+ json_content = {}\n+ else:\n+ try:\n+ json_content = json.loads(normalize_json_output(raw_content))\n+ # Check if parsed JSON is empty\n+ if not json_content or json_content == {}:\n+ self._logger.warning("Model returned empty JSON object. Attempting to find JSON in response...")\n+ # Try to find JSON in the response\n+ try:\n+ json_content = jsonfinder.only_json(raw_content)[2]\n+ if json_content and json_content != {}:\n+ self._logger.info("Found valid JSON content within response.")\n+ except Exception:\n+ self._logger.error(f"Could not extract valid JSON from response: {raw_content}")\n+ except json.JSONDecodeError as e:\n+ self._logger.warning(f"Invalid JSON returned by {self.model_name}:\n{raw_content}")\n+ try:\n+ # Try to extract JSON using jsonfinder\n+ json_content = jsonfinder.only_json(raw_content)[2]\n+ self._logger.warning("Found JSON content within model response; continuing...")\n+ except Exception as finder_error:\n+ self._logger.error(\n+ f"\n\u274c Could not parse JSON from model response.\n"\n+ f"Raw response: {raw_content}\n"\n+ f"Error: {finder_error}\n"\n+ f"Model '{self.model_name}' may not be compatible.\n"\n+ f"Consider switching to a model that supports structured output.\n"\n+ )\n+ json_content = {}\n+\n+ try:\n+ content = self.schema.model_validate(json_content)\n+\n+ assert response.usage\n+\n+ return SchematicGenerationResult(\n+ content=content,\n+ info=GenerationInfo(\n+ schema_name=self.schema.name,\n+ model=self.id,\n+ duration=(t_end - t_start),\n+ usage=UsageInfo(\n+ input_tokens=response.usage.prompt_tokens,\n+ output_tokens=response.usage.completion_tokens,\n+ extra={\n+ "cached_input_tokens": getattr(\n+ response.usage,\n+ "prompt_cache_hit_tokens",\n+ 0,\n+ )\n+ },\n+ ),\n+ ),\n+ )\n+ except ValidationError as e:\n+ self._logger.error(\n+ f"\n\u274c JSON content returned by '{self.model_name}' does not match expected schema.\n"\n+ f"Schema: {self.schema.name}\n"\n+ f"Raw response: {raw_content}\n"\n+ f"Parsed JSON: {json.dumps(json_content, indent=2) if json_content else 'Empty'}\n"\n+ f"Validation errors: {str(e)}\n"\n+ f"This model may not be producing valid structured output.\n"\n+ f"Consider switching to a model that supports JSON mode.\n"\n+ )\n+ raise\n+\n+\n+class OpenRouterGPT4O(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(model_name="openai/gpt-4o", logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 128 * 1024\n+\n+\n+class OpenRouterGPT4OMini(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(model_name="openai/gpt-4o-mini", logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 128 * 1024\n+\n+\n+class OpenRouterClaude35Sonnet(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(model_name="anthropic/claude-3.5-sonnet", logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 8192\n+\n+\n+class OpenRouterLlama33_70B(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(model_name="meta-llama/llama-3.3-70b-instruct", logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 8192\n+\n+\n+class OpenRouterEmbedder(BaseEmbedder):\n+ supported_arguments = ["dimensions"]\n+\n+ # Known embedding model dimensions\n+ _KNOWN_DIMENSIONS: dict[str, int] = {\n+ "openai/text-embedding-3-large": 3072,\n+ "openai/text-embedding-3-small": 1536,\n+ "openai/text-embedding-ada-002": 1536,\n+ "qwen/qwen3-embedding-8b": 4096,\n+ "qwen/qwen-embedding-v2": 1536,\n+ }\n+\n+ def init(self, model_name: str, logger: Logger, meter: Meter) -> None:\n+ super().init(logger, meter, model_name)\n+ self.model_name = model_name\n+\n+ # Build extra headers from environment variables\n+ extra_headers = {}\n+ if "OPENROUTER_HTTP_REFERER" in os.environ:\n+ extra_headers["HTTP-Referer"] = os.environ["OPENROUTER_HTTP_REFERER"]\n+ if "OPENROUTER_SITE_NAME" in os.environ:\n+ extra_headers["X-Title"] = os.environ["OPENROUTER_SITE_NAME"]\n+\n+ self._client = AsyncClient(\n+ base_url="https://openrouter.ai/api/v1\",\n+ api_key=os.environ["OPENROUTER_API_KEY"],\n+ default_headers=extra_headers if extra_headers else None,\n+ )\n+ self._tokenizer = OpenRouterEstimatingTokenizer(model_name=self.model_name)\n+ # Cache dimensions after first API call if not known\n+ self._cached_dimensions: int | None = None\n+\n+ @Property\n+ @OverRide\n+ def id(self) -> str:\n+ return f"openrouter/{self.model_name}"\n+\n+ @Property\n+ @OverRide\n+ def tokenizer(self) -> OpenRouterEstimatingTokenizer:\n+ return self._tokenizer\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ # Default max tokens for embedding models\n+ return 8192\n+\n+ @Property\n+ @OverRide\n+ def dimensions(self) -> int:\n+ # Check environment variable override first\n+ if "OPENROUTER_EMBEDDER_DIMENSIONS" in os.environ:\n+ return int(os.environ["OPENROUTER_EMBEDDER_DIMENSIONS"])\n+ \n+ # Return cached dimensions if available\n+ if self._cached_dimensions is not None:\n+ return self._cached_dimensions\n+ \n+ # Check known dimensions lookup\n+ for model_key, dims in self._KNOWN_DIMENSIONS.items():\n+ if model_key in self.model_name:\n+ return dims\n+ \n+ # Default fallback - most embedding models use 1536 or 3072\n+ # This will be updated after first API call\n+ return 1536\n+\n+ @Policy(\n+ [\n+ retry(\n+ exceptions=(\n+ APIConnectionError,\n+ APITimeoutError,\n+ ConflictError,\n+ RateLimitError,\n+ APIResponseValidationError,\n+ ),\n+ ),\n+ retry(InternalServerError, max_exceptions=2, wait_times=(1.0, 5.0)),\n+ ]\n+ )\n+ @OverRide\n+ async def do_embed(\n+ self,\n+ texts: list[str],\n+ hints: Mapping[str, Any] = {},\n+ ) -> EmbeddingResult:\n+ filtered_hints = {k: v for k, v in hints.items() if k in self.supported_arguments}\n+ try:\n+ response = await self._client.embeddings.create(\n+ model=self.model_name,\n+ input=texts,\n+ **filtered_hints,\n+ )\n+ except RateLimitError:\n+ self.logger.error(\n+ f"\n\u23f1\ufe0f Rate limit exceeded for embedder model '{self.model_name}'.\n"\n+ f"{RATE_LIMIT_ERROR_MESSAGE}\n"\n+ f"Consider:\n"\n+ f" - Using a different embedder model\n"\n+ f" - Waiting a moment before retrying\n"\n+ f" - Adding your own API key for higher limits\n"\n+ )\n+ raise\n+\n+ vectors = [data_point.embedding for data_point in response.data]\n+ \n+ # Cache dimensions from first response if not already cached and not in known list\n+ if self._cached_dimensions is None and vectors:\n+ actual_dims = len(vectors[0])\n+ # Only cache if different from default or if not found in known dimensions\n+ if actual_dims != 1536 or not any(key in self.model_name for key in self._KNOWN_DIMENSIONS):\n+ self._cached_dimensions = actual_dims\n+ self.logger.debug(\n+ f"Detected embedding dimensions for '{self.model_name}': {actual_dims}"\n+ )\n+ \n+ return EmbeddingResult(vectors=vectors)\n+\n+\n+class OpenRouterTextEmbedding3Large(OpenRouterEmbedder):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(model_name="openai/text-embedding-3-large", logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 8192\n+\n+ @Property\n+ @OverRide\n+ def dimensions(self) -> int:\n+ return 3072\n+\n+\n+class OpenRouterService(NLPService):\n+ @staticmethod\n+ def verify_environment() -> str | None:\n+ """Returns an error message if the environment is not set up correctly."""\n+\n+ if not os.environ.get("OPENROUTER_API_KEY"):\n+ return """\\n+You're using the OpenRouter NLP service, but OPENROUTER_API_KEY is not set.\n+Please set OPENROUTER_API_KEY in your environment before running Parlant.\n+"""\n+\n+ return None\n+\n+ def init(\n+ self,\n+ logger: Logger,\n+ meter: Meter,\n+ model_name: str | None = None,\n+ max_tokens: int | None = None,\n+ embedder_model_name: str | None = None,\n+ ) -> None:\n+ self._logger = logger\n+ self._meter = meter\n+ self._logger.info("Initialized OpenRouterService")\n+ # Use provided model_name or fall back to environment variable\n+ self.model_name = model_name or os.environ.get("OPENROUTER_MODEL", "openai/gpt-4o")\n+ self._custom_max_tokens = max_tokens\n+ # Use provided embedder_model_name or fall back to environment variable or default\n+ self.embedder_model_name = (\n+ embedder_model_name\n+ or os.environ.get("OPENROUTER_EMBEDDER_MODEL", "openai/text-embedding-3-large")\n+ )\n+ self._logger.info(f"OpenRouter model name: {self.model_name}")\n+ self._logger.info(f"OpenRouter embedder model name: {self.embedder_model_name}")\n+ \n+ # Create dynamic embedder class that can be resolved from the container\n+ # This captures embedder_model_name in a closure so the container can resolve it\n+ embedder_model = self.embedder_model_name\n+ \n+ class DynamicOpenRouterEmbedder(OpenRouterEmbedder):\n+ def init(self, logger: Logger, meter: Meter):\n+ super().init(model_name=embedder_model, logger=logger, meter=meter)\n+ \n+ self._dynamic_embedder_class = DynamicOpenRouterEmbedder\n+\n+ def _get_specialized_generator_class(\n+ self,\n+ model_name: str,\n+ t: type[T],\n+ ) -> Callable[[Logger, Meter], OpenRouterSchematicGenerator[T]]:\n+ """\n+ Returns the specialized generator class for known models.\n+ For unknown models, creates a dynamic generator that works with any OpenRouter model.\n+ """\n+ model_mapping: dict[str, Callable[[Logger, Meter], OpenRouterSchematicGenerator[T]]] = {\n+ "openai/gpt-4o": lambda logger, meter: OpenRouterGPT4O[t](logger, meter), # type: ignore\n+ "openai/gpt-4o-mini": lambda logger, meter: OpenRouterGPT4OMini[t](logger, meter), # type: ignore\n+ "anthropic/claude-3.5-sonnet": lambda logger, meter: OpenRouterClaude35Sonnet[t](logger, meter), # type: ignore\n+ "meta-llama/llama-3.3-70b-instruct": lambda logger, meter: OpenRouterLlama33_70B[t](logger, meter), # type: ignore\n+ }\n+\n+ # Check if we have a predefined generator for this model\n+ if generator_factory := model_mapping.get(model_name):\n+ return generator_factory\n+ \n+ # Create a dynamic generator for any OpenRouter model\n+ # Get max_tokens from parameter, environment variable, or use sensible defaults based on model name\n+ if self._custom_max_tokens is not None:\n+ max_tokens = self._custom_max_tokens\n+ else:\n+ max_tokens_str = os.environ.get("OPENROUTER_MAX_TOKENS")\n+ if max_tokens_str:\n+ max_tokens = int(max_tokens_str)\n+ else:\n+ # Provide sensible defaults based on model family\n+ if "gpt-4" in model_name:\n+ max_tokens = 128 * 1024\n+ elif "claude" in model_name:\n+ max_tokens = 8192\n+ elif "llama" in model_name or "gemma" in model_name:\n+ max_tokens = 8192\n+ else:\n+ max_tokens = 8192 # Safe default for unknown models\n+ \n+ # Create dynamic generator class with the specific max_tokens\n+ final_max_tokens = max_tokens\n+ \n+ class DynamicOpenRouterGenerator(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter):\n+ super().init(model_name=model_name, logger=logger, meter=meter)\n+ \n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return final_max_tokens\n+ \n+ # Return a factory function that creates the properly typed instance\n+ def create_generator(logger: Logger, meter: Meter) -> OpenRouterSchematicGenerator[T]:\n+ return DynamicOpenRouterGenerator[t](logger, meter) # type: ignore\n+ \n+ return create_generator\n+\n+ @OverRide\n+ async def get_schematic_generator(self, t: type[T]) -> OpenRouterSchematicGenerator[T]:\n+ generator_factory = self._get_specialized_generator_class(self.model_name, t)\n+ return generator_factory(self._logger, self._meter)\n+\n+ @OverRide\n+ async def get_embedder(self) -> Embedder:\n+ # Use OpenRouter embedder with the configured embedder model name\n+ # Default to text-embedding-3-large if not specified\n+ if self.embedder_model_name == "openai/text-embedding-3-large":\n+ return OpenRouterTextEmbedding3Large(logger=self._logger, meter=self._meter)\n+ else:\n+ # Return instance of dynamic embedder class that can be resolved from container\n+ return self._dynamic_embedder_class(logger=self._logger, meter=self._meter)\n+\n+ @OverRide\n+ async def get_moderation_service(self) -> ModerationService:\n+ return NoModeration()\ndiff --git a/src/parlant/sdk.py b/src/parlant/sdk.py\nindex e5ab96af1..5ab00223d 100644\n--- a/src/parlant/sdk.py\n+++ b/src/parlant/sdk.py\n@@ -408,6 +408,36 @@ def fireworks(container: Container) -> NLPService:\n \n return FireworksService(container[Logger], container[Meter])\n \n+ @staticmethod\n+ def openrouter(\n+ container: Container | None = None,\n+ model_name: str | None = None,\n+ max_tokens: int | None = None,\n+ embedder_model_name: str | None = None,\n+ ) -> NLPService | Callable[[Container], NLPService]:\n+ """\n+ Returns a callable that creates an OpenRouter NLPService instance using the provided container.\n+ If container is None, the callable expects the container to be provided later (by the Server).\n+ If model_name, max_tokens, or embedder_model_name are None, environment variables will be used.\n+ """\n+ from parlant.adapters.nlp.openrouter_service import OpenRouterService\n+\n+ def factory(c: Container) -> NLPService:\n+ if error := OpenRouterService.verify_environment():\n+ raise SDKError(error)\n+ return OpenRouterService(\n+ c[Logger],\n+ c[Meter],\n+ model_name=model_name,\n+ max_tokens=max_tokens,\n+ embedder_model_name=embedder_model_name,\n+ )\n+\n+ if container is not None:\n+ return factory(container)\n+\n+ return factory\n+\n \n class _CachedGuidelineEvaluation(TypedDict, total=False):\n id: ObjectId\ndiff --git a/tests/adapters/nlp/test_openrouter_service.py b/tests/adapters/nlp/test_openrouter_service.py\nnew file mode 100644\nindex 000000000..2cad85e86\n--- /dev/null\n+++ b/tests/adapters/nlp/test_openrouter_service.py\n@@ -0,0 +1,374 @@\n+# Copyright 2025 Emcie Co Ltd.\n+#\n+# Licensed under the Apache License, Version 2.0 (the "License");\n+# you may not use this file except in compliance with the License.\n+# You may obtain a copy of the License at\n+#\n+# http://www.apache.org/licenses/LICENSE-2.0\n+#\n+# Unless required by applicable law or agreed to in writing, software\n+# distributed under the License is distributed on an "AS IS" BASIS,\n+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n+# See the License for the specific language governing permissions and\n+# limitations under the License.\n+\n+import os\n+from lagom import Container\n+import pytest\n+from unittest.mock import AsyncMock, patch, Mock\n+import asyncio\n+from openai.types.chat import ChatCompletion, ChatCompletionMessage\n+from openai.types.chat.chat_completion import Choice\n+from openai.types.completion_usage import CompletionUsage\n+\n+from parlant.adapters.nlp.openrouter_service import ( # type: ignore[reportMissingImports]\n+ OpenRouterService,\n+ OpenRouterSchematicGenerator,\n+ OpenRouterGPT4O,\n+ OpenRouterGPT4OMini,\n+ OpenRouterClaude35Sonnet,\n+ OpenRouterLlama33_70B,\n+ OpenRouterEstimatingTokenizer,\n+)\n+from parlant.core.loggers import Logger\n+from parlant.core.common import DefaultBaseModel\n+from parlant.core.meter import Meter\n+\n+\n+class TestSchemaData(DefaultBaseModel):\n+ """Test schema for type checking."""\n+\n+ test_field: str = "test_value"\n+\n+\n+def test_that_missing_openrouter_api_key_returns_error_message() -> None:\n+ """Test that missing OPENROUTER_API_KEY returns error message."""\n+ with patch.dict(os.environ, {}, clear=True):\n+ error = OpenRouterService.verify_environment()\n+ assert error is not None\n+ assert "OPENROUTER_API_KEY is not set" in error\n+\n+\n+def test_that_present_api_key_returns_none() -> None:\n+ """Test that present API key returns None (success)."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ error = OpenRouterService.verify_environment()\n+ assert error is None\n+\n+\n+def test_that_openrouter_service_initializes_with_default_model() -> None:\n+ """Test OpenRouterService initialization with default model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(logger=mock_logger, meter=mock_meter)\n+ assert service.model_name == "openai/gpt-4o"\n+\n+\n+def test_that_openrouter_service_initializes_with_custom_model() -> None:\n+ """Test OpenRouterService initialization with custom model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(\n+ logger=mock_logger,\n+ meter=mock_meter,\n+ model_name="anthropic/claude-3.5-sonnet",\n+ )\n+ assert service.model_name == "anthropic/claude-3.5-sonnet"\n+\n+\n+def test_that_openrouter_service_uses_environment_model() -> None:\n+ """Test OpenRouterService uses OPENROUTER_MODEL from environment."""\n+ with patch.dict(\n+ os.environ,\n+ {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MODEL": "meta-llama/llama-3.3-70b-instruct"},\n+ clear=True,\n+ ):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(logger=mock_logger, meter=mock_meter)\n+ assert service.model_name == "meta-llama/llama-3.3-70b-instruct"\n+\n+\n+def test_that_openrouter_service_respects_custom_max_tokens() -> None:\n+ """Test OpenRouterService respects custom max_tokens parameter."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(\n+ logger=mock_logger, meter=mock_meter, max_tokens=4096\n+ )\n+ assert service._custom_max_tokens == 4096\n+\n+\n+def test_that_openrouter_estimating_tokenizer_works(container: Container) -> None:\n+ """Test OpenRouterEstimatingTokenizer token estimation."""\n+ tokenizer = OpenRouterEstimatingTokenizer(model_name="openai/gpt-4o")\n+ tokens = asyncio.run(tokenizer.estimate_token_count("Hello world"))\n+ assert tokens > 0\n+\n+\n+def test_that_openrouter_gpt4o_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterGPT4O initialization."""\n+ generator = OpenRouterGPT4O[TestSchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "openai/gpt-4o"\n+ assert generator.id == "openrouter/openai/gpt-4o"\n+ assert generator.max_tokens == 128 * 1024\n+\n+\n+def test_that_openrouter_gpt4o_mini_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterGPT4OMini initialization."""\n+ generator = OpenRouterGPT4OMini[TestSchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "openai/gpt-4o-mini"\n+ assert generator.max_tokens == 128 * 1024\n+\n+\n+def test_that_openrouter_claude_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterClaude35Sonnet initialization."""\n+ generator = OpenRouterClaude35Sonnet[TestSchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "anthropic/claude-3.5-sonnet"\n+ assert generator.max_tokens == 8192\n+\n+\n+def test_that_openrouter_llama_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterLlama33_70B initialization."""\n+ generator = OpenRouterLlama33_70B[TestSchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "meta-llama/llama-3.3-70b-instruct"\n+ assert generator.max_tokens == 8192\n+\n+\n+@patch("parlant.adapters.nlp.openrouter_service.AsyncClient")\n+def test_that_openrouter_generator_sets_custom_headers(mock_client_class) -> None:\n+ """Test that OpenRouter generator sets custom headers from environment."""\n+ with patch.dict(\n+ os.environ,\n+ {\n+ "OPENROUTER_API_KEY": "test-key",\n+ "OPENROUTER_HTTP_REFERER": "https://example.com\",\n+ "OPENROUTER_SITE_NAME": "My App",\n+ },\n+ clear=True,\n+ ):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ generator = OpenRouterSchematicGenerator[TestSchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=mock_logger,\n+ meter=mock_meter,\n+ )\n+\n+ # Verify client was called with headers\n+ mock_client_class.assert_called_once()\n+ call_args = mock_client_class.call_args\n+ assert "default_headers" in call_args[1]\n+ assert call_args[1]["default_headers"]["HTTP-Referer"] == "https://example.com\"\n+ assert call_args[1]["default_headers"]["X-Title"] == "My App"\n+\n+\n+@patch("parlant.adapters.nlp.openrouter_service.AsyncClient")\n+def test_that_openrouter_generator_without_custom_headers(mock_client_class) -> None:\n+ """Test OpenRouter generator without custom headers."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ generator = OpenRouterSchematicGenerator[TestSchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=mock_logger,\n+ meter=mock_meter,\n+ )\n+\n+ # Verify client was called without custom headers\n+ mock_client_class.assert_called_once()\n+ call_args = mock_client_class.call_args\n+ assert call_args[1]["default_headers"] is None\n+\n+\n+@patch("parlant.adapters.nlp.openrouter_service.AsyncClient")\n+async def test_that_openrouter_generator_handles_json_mode_error(mock_client_class) -> None:\n+ """Test that OpenRouter generator handles JSON mode errors gracefully."""\n+ mock_client = AsyncMock()\n+ mock_client_class.return_value = mock_client\n+\n+ # Mock BadRequestError for JSON mode\n+ from openai import BadRequestError\n+\n+ mock_client.chat.completions.create.side_effect = BadRequestError(\n+ "Model does not support JSON mode", body={"error": {"message": "JSON mode error"}}, response=Mock()\n+ )\n+\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+\n+ generator = OpenRouterSchematicGenerator[TestSchemaData](\n+ model_name="test-model",\n+ logger=mock_logger,\n+ meter=mock_meter,\n+ )\n+\n+ # Should fail since we're mocking the error\n+ with pytest.raises(BadRequestError):\n+ await generator.do_generate("Test prompt")\n+\n+\n+async def test_that_openrouter_generator_handles_successful_response(\n+ container: Container,\n+) -> None:\n+ """Test OpenRouter generator with successful JSON response."""\n+ mock_response = Mock(spec=ChatCompletion)\n+ mock_response.choices = [\n+ Choice(\n+ message=ChatCompletionMessage(role="assistant", content='{"test_field": "test_value"}'),\n+ finish_reason="stop",\n+ index=0,\n+ )\n+ ]\n+ mock_response.usage = CompletionUsage(\n+ prompt_tokens=10, completion_tokens=20, total_tokens=30\n+ )\n+\n+ with patch("parlant.adapters.nlp.openrouter_service.AsyncClient") as mock_client_class:\n+ mock_client = AsyncMock()\n+ mock_client.chat.completions.create = AsyncMock(return_value=mock_response)\n+ mock_client_class.return_value = mock_client\n+\n+ generator = OpenRouterSchematicGenerator[TestSchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ )\n+\n+ result = await generator.do_generate('Generate {"test_field": "test_value"}')\n+\n+ assert result.content.test_field == "test_value"\n+ assert result.info.input_tokens == 10\n+ assert result.info.output_tokens == 20\n+\n+\n+def test_that_openrouter_service_returns_correct_generator(container: Container) -> None:\n+ """Test OpenRouterService.get_schematic_generator with default model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert isinstance(generator, OpenRouterSchematicGenerator)\n+ assert generator.model_name == "openai/gpt-4o"\n+\n+\n+def test_that_openrouter_service_returns_correct_generator_for_claude(\n+ container: Container,\n+) -> None:\n+ """Test OpenRouterService.get_schematic_generator with Claude model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ model_name="anthropic/claude-3.5-sonnet",\n+ )\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert isinstance(generator, OpenRouterClaude35Sonnet)\n+ assert generator.model_name == "anthropic/claude-3.5-sonnet"\n+\n+\n+def test_that_openrouter_service_creates_dynamic_generator_for_unknown_model(\n+ container: Container,\n+) -> None:\n+ """Test OpenRouterService creates dynamic generator for unknown model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ model_name="custom/model-name",\n+ )\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert isinstance(generator, OpenRouterSchematicGenerator)\n+ assert generator.model_name == "custom/model-name"\n+\n+\n+def test_that_openrouter_service_uses_custom_max_tokens(container: Container) -> None:\n+ """Test OpenRouterService uses custom max_tokens for unknown model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ model_name="custom/model",\n+ max_tokens=2048,\n+ )\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert generator.max_tokens == 2048\n+\n+\n+def test_that_openrouter_service_uses_environment_max_tokens(container: Container) -> None:\n+ """Test OpenRouterService uses environment max_tokens."""\n+ with patch.dict(\n+ os.environ, {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MAX_TOKENS": "4096"}, clear=True\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert generator.max_tokens == 4096\n+\n+\n+def test_that_openrouter_service_sets_default_max_tokens_for_gpt4(container: Container) -> None:\n+ """Test OpenRouterService sets default max_tokens for GPT-4 models."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ model_name="openai/gpt-4-turbo",\n+ )\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert generator.max_tokens == 128 * 1024\n+\n+\n+def test_that_openrouter_service_sets_default_max_tokens_for_claude(container: Container) -> None:\n+ """Test OpenRouterService sets default max_tokens for Claude models."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ model_name="anthropic/claude-2",\n+ )\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert generator.max_tokens == 8192\n+\n+\n+def test_that_openrouter_service_sets_default_max_tokens_for_llama(container: Container) -> None:\n+ """Test OpenRouterService sets default max_tokens for Llama models."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ model_name="meta-llama/llama-2-70b",\n+ )\n+ generator = asyncio.run(service.get_schematic_generator(TestSchemaData))\n+ assert generator.max_tokens == 8192\n+\n+\n+def test_that_openrouter_service_returns_jina_embedder(container: Container) -> None:\n+ """Test OpenRouterService returns JinaAI embedder."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ embedder = asyncio.run(service.get_embedder())\n+ # JinaAIEmbedder is used as fallback since OpenRouter doesn't have embeddings\n+ assert embedder is not None\n+\n+\n+def test_that_openrouter_service_returns_no_moderation(container: Container) -> None:\n+ """Test OpenRouterService returns NoModeration."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ moderation = asyncio.run(service.get_moderation_service())\n+ from parlant.core.nlp.moderation import NoModeration\n+ assert isinstance(moderation, NoModeration)\n+\n+\n+def test_that_openrouter_generator_supports_correct_parameters(container: Container) -> None:\n+ """Test supported OpenRouter parameters."""\n+ generator = OpenRouterSchematicGenerator[TestSchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ )\n+\n+ expected_params = ["temperature", "max_tokens"]\n+ assert generator.supported_openrouter_params == expected_params\n+\n"}, "reference_review_comments": [{"text": "@user1:\nI\u2019d avoid using emojis in log messages. They might not render properly in all environments and can cause issues with log parsers\n\n@author:\nremoved the emoji to ensure compatibility with all environments. Thanks for pointing that out!", "path": "src/parlant/adapters/nlp/openrouter_service.py", "diff_hunk": "@@ -0,0 +1,592 @@\n+# Copyright 2025 Emcie Co Ltd.\n+#\n+# Licensed under the Apache License, Version 2.0 (the "License");\n+# you may not use this file except in compliance with the License.\n+# You may obtain a copy of the License at\n+#\n+# http://www.apache.org/licenses/LICENSE-2.0\n+#\n+# Unless required by applicable law or agreed to in writing, software\n+# distributed under the License is distributed on an "AS IS" BASIS,\n+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n+# See the License for the specific language governing permissions and\n+# limitations under the License.\n+\n+from future import annotations\n+import time\n+from openai import (\n+ APIConnectionError,\n+ APIResponseValidationError,\n+ APITimeoutError,\n+ AsyncClient,\n+ BadRequestError,\n+ ConflictError,\n+ InternalServerError,\n+ RateLimitError,\n+)\n+from typing import Any, Callable, Mapping\n+from typing_extensions import override\n+import json\n+import jsonfinder # type: ignore\n+import os\n+\n+from pydantic import ValidationError\n+import tiktoken\n+\n+from parlant.adapters.nlp.common import normalize_json_output\n+from parlant.core.engines.alpha.prompt_builder import PromptBuilder\n+from parlant.core.loggers import Logger\n+from parlant.core.meter import Meter\n+from parlant.core.nlp.policies import policy, retry\n+from parlant.core.nlp.tokenization import EstimatingTokenizer\n+from parlant.core.nlp.service import NLPService\n+from parlant.core.nlp.embedding import BaseEmbedder, Embedder, EmbeddingResult\n+from parlant.core.nlp.generation import (\n+ T,\n+ BaseSchematicGenerator,\n+ SchematicGenerationResult,\n+)\n+from parlant.core.nlp.generation_info import GenerationInfo, UsageInfo\n+from parlant.core.nlp.moderation import (\n+ ModerationService,\n+ NoModeration,\n+)\n+\n+RATE_LIMIT_ERROR_MESSAGE = """\\n+OpenRouter API rate limit exceeded. Possible reasons:\n+1. Your account may have insufficient API credits.\n+2. You may be using a free-tier account with limited request capacity.\n+3. You might have exceeded the requests-per-minute limit for your account.\n+\n+Recommended actions:\n+- Check your OpenRouter account balance and billing status.\n+- Review your API usage limits in OpenRouter's dashboard.\n+- For more details on rate limits and usage tiers, visit:\n+ https://openrouter.ai/docs/api-reference/limits\n+"""\n+\n+\n+class OpenRouterEstimatingTokenizer(EstimatingTokenizer):\n+ def init(self, model_name: str) -> None:\n+ self.model_name = model_name\n+ # Use gpt-4 encoding as default for token estimation\n+ self.encoding = tiktoken.encoding_for_model("gpt-4o-2024-08-06")\n+\n+ @OverRide\n+ async def estimate_token_count(self, prompt: str) -> int:\n+ tokens = self.encoding.encode(prompt)\n+ return len(tokens)\n+\n+\n+class OpenRouterSchematicGenerator(BaseSchematicGenerator[T]):\n+ supported_openrouter_params = ["temperature", "max_tokens"]\n+\n+ def init(\n+ self,\n+ model_name: str,\n+ logger: Logger,\n+ meter: Meter,\n+ ) -> None:\n+ super().init(logger=logger, meter=meter, model_name=model_name)\n+ self._logger = logger\n+\n+ # Build extra headers from environment variables\n+ extra_headers = {}\n+ if "OPENROUTER_HTTP_REFERER" in os.environ:\n+ extra_headers["HTTP-Referer"] = os.environ["OPENROUTER_HTTP_REFERER"]\n+ if "OPENROUTER_SITE_NAME" in os.environ:\n+ extra_headers["X-Title"] = os.environ["OPENROUTER_SITE_NAME"]\n+\n+ self._client = AsyncClient(\n+ base_url="https://openrouter.ai/api/v1",\n+ api_key=os.environ["OPENROUTER_API_KEY"],\n+ default_headers=extra_headers if extra_headers else None,\n+ )\n+\n+ self._tokenizer = OpenRouterEstimatingTokenizer(model_name=self.model_name)\n+\n+ @Property \n+ @OverRide\n+ def id(self) -> str:\n+ return f"openrouter/{self.model_name}"\n+\n+ @Property\n+ @OverRide\n+ def tokenizer(self) -> OpenRouterEstimatingTokenizer:\n+ return self._tokenizer\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ # Default implementation - should be overridden by subclasses\n+ return 8192\n+\n+ @Policy(\n+ [\n+ retry(\n+ exceptions=(\n+ APIConnectionError,\n+ APITimeoutError,\n+ ConflictError,\n+ RateLimitError,\n+ APIResponseValidationError,\n+ ),\n+ ),\n+ retry(InternalServerError, max_exceptions=2, wait_times=(1.0, 5.0)),\n+ ]\n+ )\n+ @OverRide\n+ async def do_generate(\n+ self,\n+ prompt: str | PromptBuilder,\n+ hints: Mapping[str, Any] = {},\n+ ) -> SchematicGenerationResult[T]:\n+ if isinstance(prompt, PromptBuilder):\n+ prompt = prompt.build()\n+\n+ openrouter_api_arguments = {\n+ k: v for k, v in hints.items() if k in self.supported_openrouter_params\n+ }\n+\n+ t_start = time.time()\n+ \n+ # Try with JSON mode first, but catch errors gracefully\n+ response = None\n+ \n+ try:\n+ # Try with JSON mode\n+ response = await self._client.chat.completions.create(\n+ messages=[{"role": "user", "content": prompt}],\n+ model=self.model_name,\n+ response_format={"type": "json_object"},\n+ **openrouter_api_arguments,\n+ )\n+ except BadRequestError as e:\n+ # Check if it's a JSON mode error\n+ error_str = str(e)\n+ if "JSON mode" in error_str or "json_object" in error_str.lower():\n+ self._logger.error(\n+ f"\n\u26a0\ufe0f Model '{self.model_name}' does not support JSON mode.\n"", "line": null, "start_line": null, "original_line": 169, "original_start_line": null}], "merged_commit": "fccd66e3459c699f1e64b56ec1d3523c1cc22d0c", "merged_patch": "diff --git a/docs/adapters/nlp/openrouter.md b/docs/adapters/nlp/openrouter.md\nnew file mode 100644\nindex 000000000..309d8a752\n--- /dev/null\n+++ b/docs/adapters/nlp/openrouter.md\n@@ -0,0 +1,554 @@\n+# OpenRouter Service Documentation\n+\n+The OpenRouter service provides access to 400+ AI models through a single unified API, including GPT-4, Claude, Llama, Qwen, and many more. OpenRouter makes it easy to switch between different models for both text generation and embeddings without changing code.\n+\n+## Prerequisites\n+\n+1. OpenRouter Account: Sign up at openrouter.ai\n+2. API Key: Get your API key from the OpenRouter dashboard\n+3. Model Access: Ensure you have access to the models you want to use\n+\n+## Quick Start\n+\n+### Basic Setup\n+\n+bash\n+# Set your OpenRouter API key (required)\n+export OPENROUTER_API_KEY=\"your-api-key-here\"\n+\n+# Optionally set default models\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-large\"\n+\n+\n+### Minimal Example\n+\n+python\n+import parlant.sdk as p\n+from parlant.sdk import NLPServices\n+\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"AI Assistant\",\n+ description=\"A helpful assistant powered by OpenRouter.\",\n+ )\n+ # \ud83c\udf89 Ready to use at http://localhost:8800\n+\n+\n+## Configuration\n+\n+All configuration is done via environment variables. Set the required and optional environment variables before running your application:\n+\n+bash\n+# Required: API Key\n+export OPENROUTER_API_KEY=\"your-api-key-here\"\n+\n+# Optional: LLM Configuration\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_MAX_TOKENS=\"128000\"\n+\n+# Optional: Embedding Configuration\n+export OPENROUTER_EMBEDDER_MODEL=\"qwen/qwen3-embedding-8b\"\n+export OPENROUTER_EMBEDDER_DIMENSIONS=\"4096\" # Optional override\n+\n+# Optional: Analytics\n+export OPENROUTER_HTTP_REFERER=\"https://myapp.com\"\n+export OPENROUTER_SITE_NAME=\"My Application\"\n+\n+\n+## Environment Variables Reference\n+\n+### Required Variables\n+\n+| Variable | Description | Example |\n+|----------|-------------|---------|\n+| OPENROUTER_API_KEY | Your OpenRouter API key | sk-or-v1-... |\n+\n+### Optional Variables - LLM Configuration\n+\n+| Variable | Description | Default | Example |\n+|----------|-------------|---------|---------|\n+| OPENROUTER_MODEL | LLM model name | openai/gpt-4o | openai/gpt-4o-mini |\n+| OPENROUTER_MAX_TOKENS | Max tokens limit | Auto-detected | 128000 |\n+\n+### Optional Variables - Embedding Configuration\n+\n+| Variable | Description | Default | Example |\n+|----------|-------------|---------|---------|\n+| OPENROUTER_EMBEDDER_MODEL | Embedding model name | openai/text-embedding-3-large | qwen/qwen3-embedding-8b |\n+| OPENROUTER_EMBEDDER_DIMENSIONS | Override embedding dimensions | Auto-detected | 4096 |\n+\n+### Optional Variables - Analytics\n+\n+| Variable | Description | Example |\n+|----------|-------------|---------|\n+| OPENROUTER_HTTP_REFERER | Your app's URL (for analytics) | https://myapp.com |\n+| OPENROUTER_SITE_NAME | Your app's name (for analytics) | My Application |\n+\n+## Supported Models\n+\n+OpenRouter supports 400+ models from different providers. Models are automatically optimized with specialized configurations when available.\n+\n+### Pre-configured LLM Models\n+\n+These models have specialized configurations for optimal performance:\n+\n+| Model | Provider | Context | Use Case |\n+|-------|----------|---------|----------|\n+| openai/gpt-4o | OpenAI | 128K | Default, best overall quality |\n+| openai/gpt-4o-mini | OpenAI | 128K | Cost-effective, fast |\n+| anthropic/claude-3.5-sonnet | Anthropic | 200K | Advanced reasoning, long context |\n+| meta-llama/llama-3.3-70b-instruct | Meta | 8K | Open-source option |\n+\n+### Supported Embedding Models\n+\n+The service supports multiple embedding models with automatic dimension detection:\n+\n+| Model | Dimensions | Provider | Use Case |\n+|-------|------------|----------|----------|\n+| openai/text-embedding-3-large | 3072 | OpenAI | Default, high quality |\n+| openai/text-embedding-3-small | 1536 | OpenAI | Faster, smaller |\n+| openai/text-embedding-ada-002 | 1536 | OpenAI | Legacy model |\n+| qwen/qwen3-embedding-8b | 4096 | Qwen | High dimension, multilingual |\n+| qwen/qwen-embedding-v2 | 1536 | Qwen | Multilingual embeddings |\n+\n+### Using Any OpenRouter Model\n+\n+You can use any model that OpenRouter supports by setting the appropriate environment variables:\n+\n+bash\n+# LLM Models\n+export OPENROUTER_MODEL=\"google/gemini-pro-1.5\"\n+\n+# Embedding Models\n+export OPENROUTER_EMBEDDER_MODEL=\"qwen/qwen3-embedding-8b\"\n+\n+\n+Check the OpenRouter Models page for the full list of available models.\n+\n+## Usage Examples\n+\n+### Example 1: Default Configuration\n+\n+Use the default models (GPT-4o for LLM, text-embedding-3-large for embeddings):\n+\n+python\n+import parlant.sdk as p\n+from parlant.sdk import NLPServices\n+\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"General Assistant\",\n+ description=\"A helpful AI assistant.\"\n+ )\n+\n+\n+### Example 2: Custom LLM Model\n+\n+Use Claude for text generation:\n+\n+bash\n+export OPENROUTER_MODEL=\"anthropic/claude-3.5-sonnet\"\n+\n+\n+python\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"Claude Assistant\",\n+ description=\"Powered by Claude.\"\n+ )\n+\n+\n+### Example 3: Custom Embedder Model\n+\n+Use a custom embedding model for better multilingual support:\n+\n+bash\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"qwen/qwen3-embedding-8b\"\n+\n+\n+python\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"Multilingual Assistant\",\n+ description=\"Supports multiple languages.\"\n+ )\n+\n+\n+### Example 4: High-Performance Setup\n+\n+Optimize for speed and quality:\n+\n+bash\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-large\"\n+export OPENROUTER_MAX_TOKENS=\"128000\"\n+\n+\n+python\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"High-Performance Agent\",\n+ description=\"Optimized for speed and accuracy.\"\n+ )\n+\n+\n+### Example 5: Cost-Optimized Setup\n+\n+Balance quality and cost:\n+\n+bash\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-small\"\n+\n+\n+python\n+async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"Cost-Optimized Agent\",\n+ description=\"Optimized for cost-effectiveness.\"\n+ )\n+\n+\n+## Embedding Model Configuration\n+\n+### Understanding Embedding Dimensions\n+\n+Different embedding models produce vectors of different dimensions. The service automatically detects dimensions for known models, and can auto-detect from API responses for unknown models.\n+\n+### Known Embedding Dimensions\n+\n+The following models have pre-configured dimensions:\n+\n+- openai/text-embedding-3-large: 3072 dimensions\n+- openai/text-embedding-3-small: 1536 dimensions\n+- openai/text-embedding-ada-002: 1536 dimensions\n+- qwen/qwen3-embedding-8b: 4096 dimensions\n+- qwen/qwen-embedding-v2: 1536 dimensions\n+\n+### Auto-Detection\n+\n+For unknown models, dimensions are automatically detected from the first API response and cached for subsequent use.\n+\n+### Manual Dimension Override\n+\n+If needed, you can manually specify dimensions via environment variable:\n+\n+bash\n+export OPENROUTER_EMBEDDER_DIMENSIONS=\"4096\"\n+\n+\n+\u26a0\ufe0f Important: If you change embedder models or dimensions, you may need to clear your vector database cache to avoid dimension mismatch errors.\n+\n+## Dynamic Model Selection\n+\n+OpenRouter intelligently handles model selection and configuration:\n+\n+### Automatic Generator Selection\n+\n+Known models use specialized generators for optimal performance:\n+\n+- openai/gpt-4o \u2192 OpenRouterGPT4O\n+- openai/gpt-4o-mini \u2192 OpenRouterGPT4OMini\n+- anthropic/claude-3.5-sonnet \u2192 OpenRouterClaude35Sonnet\n+- meta-llama/llama-3.3-70b-instruct \u2192 OpenRouterLlama33_70B\n+- Other models \u2192 Dynamic generator with auto-configured parameters\n+\n+### Automatic Embedder Selection\n+\n+Embedders are automatically configured based on the model name:\n+\n+- Known models \u2192 Pre-configured dimensions\n+- Unknown models \u2192 Auto-detected dimensions from API response\n+- Dynamic embedder \u2192 Created with proper container resolution\n+\n+## Advantages of OpenRouter\n+\n+1. Model Diversity: Access to 400+ models from different providers\n+2. Unified Embeddings: Native support for embedding models via the same API\n+3. Cost Flexibility: Choose models based on price-performance needs\n+4. Single API: One integration for multiple providers\n+5. Auto-Optimization: Automatic configuration for known models\n+6. Environment-Based Configuration: All configuration via environment variables\n+7. Analytics: Built-in usage tracking through OpenRouter dashboard\n+\n+## Troubleshooting\n+\n+### Rate Limit Errors\n+\n+Error:\n+\n+OpenRouter API rate limit exceeded\n+\n+\n+Solutions:\n+- Check your OpenRouter account balance and billing status\n+- Review usage limits in the OpenRouter dashboard\n+- Consider upgrading your plan for higher limits\n+- Try a different model with higher rate limits\n+- Wait a moment before retrying\n+\n+### JSON Mode Not Supported\n+\n+Error:\n+\n+Model 'xyz' does not support JSON mode\n+\n+\n+Solutions:\n+- OpenRouter automatically falls back to prompting for JSON output\n+- Consider using a model that supports JSON mode:\n+ - openai/gpt-4o\n+ - openai/gpt-4o-mini\n+ - anthropic/claude-3.5-sonnet\n+- The fallback still produces structured output reliably\n+\n+### Dimension Mismatch Errors\n+\n+Error:\n+\n+ValueError: all the input array dimensions except for the concatenation axis must match exactly\n+\n+\n+Solutions:\n+- This occurs when switching embedder models with different dimensions\n+- Clear your vector database cache/embeddings\n+- Or delete the cached embeddings files in your parlant-data directory\n+- The embedder will create new embeddings with the correct dimensions\n+\n+### Authentication Errors\n+\n+Error:\n+\n+OPENROUTER_API_KEY is not set\n+\n+\n+Solutions:\n+- Set the OPENROUTER_API_KEY environment variable\n+- Verify your API key in the OpenRouter dashboard\n+- Ensure the key hasn't expired or been revoked\n+- Check for typos in the environment variable name\n+\n+### Container Resolution Errors\n+\n+Error:\n+\n+Unable to construct dependency of type OpenRouterEmbedder\n+\n+\n+Solutions:\n+- This is automatically handled by the dynamic embedder class\n+- Ensure you're using the latest version of the code\n+- If the error persists, check that embedder_model_name is correctly set\n+\n+## Cost Management\n+\n+OpenRouter provides transparent pricing across models. Choose models based on your needs:\n+\n+### Cost-Effective LLM Options\n+\n+python\n+# GPT-4o-mini - Good quality, lower cost\n+model_name=\"openai/gpt-4o-mini\"\n+\n+# Claude Haiku - Fast, affordable\n+model_name=\"anthropic/claude-3-haiku\"\n+\n+# Llama - Open source, very affordable\n+model_name=\"meta-llama/llama-3.3-70b-instruct\"\n+\n+\n+### Cost-Effective Embedding Options\n+\n+python\n+# text-embedding-3-small - Smaller, faster, cheaper\n+embedder_model_name=\"openai/text-embedding-3-small\"\n+\n+# text-embedding-ada-002 - Legacy, very affordable\n+embedder_model_name=\"openai/text-embedding-ada-002\"\n+\n+\n+### Premium Options\n+\n+python\n+# GPT-4o - Highest quality\n+model_name=\"openai/gpt-4o\"\n+\n+# text-embedding-3-large - Highest quality embeddings\n+embedder_model_name=\"openai/text-embedding-3-large\"\n+\n+\n+Check OpenRouter pricing for current rates.\n+\n+## Model Selection Guide\n+\n+### When to Use Each LLM Model\n+\n+GPT-4o (openai/gpt-4o)\n+- Complex reasoning tasks\n+- Code generation and debugging\n+- Multi-step problem solving\n+- When accuracy is critical\n+- Best overall performance\n+\n+GPT-4o-mini (openai/gpt-4o-mini)\n+- General purpose tasks\n+- High-volume applications\n+- Cost-sensitive use cases\n+- When 95% accuracy is sufficient\n+- Fast response times\n+\n+Claude (anthropic/claude-3.5-sonnet)\n+- Long context tasks (200K tokens)\n+- Creative writing\n+- Detailed analysis\n+- When you need extended reasoning\n+- Complex document understanding\n+\n+Llama (meta-llama/llama-3.3-70b-instruct)\n+- Open-source requirements\n+- Custom fine-tuning needs\n+- Privacy-sensitive applications\n+- Cost optimization\n+- Self-hosted deployments\n+\n+### When to Use Each Embedding Model\n+\n+text-embedding-3-large (openai/text-embedding-3-large)\n+- Default choice for most use cases\n+- High quality semantic search\n+- Best accuracy for retrieval\n+- Recommended for production\n+\n+text-embedding-3-small (openai/text-embedding-3-small)\n+- Cost-sensitive applications\n+- Faster embedding generation\n+- Good quality for most tasks\n+- Large-scale deployments\n+\n+qwen3-embedding-8b (qwen/qwen3-embedding-8b)\n+- Multilingual applications\n+- Higher dimensional space (4096)\n+- Better fine-grained distinctions\n+- When you need more embedding dimensions\n+\n+## Best Practices\n+\n+### 1. Start with Defaults\n+Begin with the default models (gpt-4o and text-embedding-3-large) for best balance of quality and performance.\n+\n+### 2. Use Mini for Scale\n+Switch to gpt-4o-mini for high-volume operations where cost is a concern.\n+\n+### 3. Match Embedder to Use Case\n+- Use text-embedding-3-large for quality-critical applications\n+- Use text-embedding-3-small for cost-sensitive deployments\n+- Use qwen3-embedding-8b for multilingual or high-dimensional needs\n+\n+### 4. Set Max Tokens\n+Prevent runaway costs by setting appropriate max_tokens limits via environment variable:\n+\n+bash\n+export OPENROUTER_MAX_TOKENS=\"128000\" # For long-context models\n+export OPENROUTER_MAX_TOKENS=\"8192\" # For standard use cases\n+\n+\n+### 5. Monitor Costs\n+Regularly check the OpenRouter dashboard to monitor usage and costs.\n+\n+### 6. Use Analytics\n+Set OPENROUTER_HTTP_REFERER and OPENROUTER_SITE_NAME to track usage across different applications.\n+\n+### 7. Clear Cache When Changing Models\n+If you switch embedder models, clear your vector database cache to avoid dimension mismatches.\n+\n+### 8. Environment Variables for Production\n+Use environment variables for production deployments instead of hardcoding values:\n+\n+bash\n+# Production configuration\n+export OPENROUTER_API_KEY=\"sk-or-v1-...\"\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-large\"\n+\n+\n+## Advanced Configuration\n+\n+### Custom Dimensions for Unknown Models\n+\n+If using an embedding model not in the known list, you can specify dimensions:\n+\n+bash\n+export OPENROUTER_EMBEDDER_MODEL=\"custom/embedding-model\"\n+export OPENROUTER_EMBEDDER_DIMENSIONS=\"2048\"\n+\n+\n+The service will also auto-detect dimensions from the first API response.\n+\n+### Combining Multiple Configurations\n+\n+All configuration is done via environment variables. Set multiple variables to configure different aspects:\n+\n+bash\n+# Set all configuration via environment variables\n+export OPENROUTER_MODEL=\"anthropic/claude-3.5-sonnet\"\n+export OPENROUTER_MAX_TOKENS=\"200000\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-large\"\n+\n+\n+## Additional Resources\n+\n+- OpenRouter Documentation\n+- Available Models\n+- API Reference\n+- Pricing Information\n+- Rate Limits\n+\n+## Example: Complete Setup\n+\n+Here's a complete example showing a production-ready setup:\n+\n+bash\n+# Set environment variables\n+export OPENROUTER_API_KEY=\"your-api-key-here\"\n+export OPENROUTER_MODEL=\"openai/gpt-4o-mini\"\n+export OPENROUTER_EMBEDDER_MODEL=\"openai/text-embedding-3-large\"\n+export OPENROUTER_MAX_TOKENS=\"32768\"\n+\n+\n+python\n+import parlant.sdk as p\n+from parlant.sdk import NLPServices\n+\n+@p.tool\n+async def get_weather(context: p.ToolContext, city: str) -> p.ToolResult:\n+ # Your weather API logic here\n+ return p.ToolResult(f\"Sunny, 72\u00b0F in {city}\")\n+\n+async def main():\n+ async with p.Server(nlp_service=NLPServices.openrouter) as server:\n+ agent = await server.create_agent(\n+ name=\"Weather Assistant\",\n+ description=\"Helps users check weather conditions.\"\n+ )\n+ \n+ await agent.create_guideline(\n+ condition=\"User asks about weather\",\n+ action=\"Get weather information using the get_weather tool\",\n+ tools=[get_weather]\n+ )\n+ \n+ # \ud83c\udf89 Ready at http://localhost:8800\n+\n+if __name__ == \"__main__\":\n+ import asyncio\n+ asyncio.run(main())\n+\n+\n+This setup provides:\n+- \u2705 Cost-effective LLM (gpt-4o-mini)\n+- \u2705 High-quality embeddings (text-embedding-3-large)\n+- \u2705 Reasonable token limit (32K)\n+- \u2705 Tool integration\n+- \u2705 Guideline-based behavior control\ndiff --git a/src/parlant/adapters/nlp/openrouter_service.py b/src/parlant/adapters/nlp/openrouter_service.py\nnew file mode 100644\nindex 000000000..7b3140e36\n--- /dev/null\n+++ b/src/parlant/adapters/nlp/openrouter_service.py\n@@ -0,0 +1,612 @@\n+# Copyright 2025 Emcie Co Ltd.\n+#\n+# Licensed under the Apache License, Version 2.0 (the "License");\n+# you may not use this file except in compliance with the License.\n+# You may obtain a copy of the License at\n+#\n+# http://www.apache.org/licenses/LICENSE-2.0\n+#\n+# Unless required by applicable law or agreed to in writing, software\n+# distributed under the License is distributed on an "AS IS" BASIS,\n+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n+# See the License for the specific language governing permissions and\n+# limitations under the License.\n+\n+from future import annotations\n+import time\n+from openai import (\n+ APIConnectionError,\n+ APIResponseValidationError,\n+ APITimeoutError,\n+ AsyncClient,\n+ BadRequestError,\n+ ConflictError,\n+ InternalServerError,\n+ RateLimitError,\n+)\n+from typing import Any, Callable, Mapping\n+from typing_extensions import override\n+import json\n+import jsonfinder # type: ignore\n+import os\n+\n+from pydantic import ValidationError\n+import tiktoken\n+\n+from parlant.adapters.nlp.common import normalize_json_output\n+from parlant.core.engines.alpha.prompt_builder import PromptBuilder\n+from parlant.core.loggers import Logger\n+from parlant.core.meter import Meter\n+from parlant.core.nlp.policies import policy, retry\n+from parlant.core.nlp.tokenization import EstimatingTokenizer\n+from parlant.core.nlp.service import NLPService\n+from parlant.core.nlp.embedding import BaseEmbedder, Embedder, EmbeddingResult\n+from parlant.core.nlp.generation import (\n+ T,\n+ BaseSchematicGenerator,\n+ SchematicGenerationResult,\n+)\n+from parlant.core.nlp.generation_info import GenerationInfo, UsageInfo\n+from parlant.core.nlp.moderation import (\n+ ModerationService,\n+ NoModeration,\n+)\n+\n+RATE_LIMIT_ERROR_MESSAGE = """\\n+OpenRouter API rate limit exceeded. Possible reasons:\n+1. Your account may have insufficient API credits.\n+2. You may be using a free-tier account with limited request capacity.\n+3. You might have exceeded the requests-per-minute limit for your account.\n+\n+Recommended actions:\n+- Check your OpenRouter account balance and billing status.\n+- Review your API usage limits in OpenRouter's dashboard.\n+- For more details on rate limits and usage tiers, visit:\n+ https://openrouter.ai/docs/api-reference/limits\n+\"\"\"\n+\n+\n+class OpenRouterEstimatingTokenizer(EstimatingTokenizer):\n+ def init(self, model_name: str) -> None:\n+ self.model_name = model_name\n+ # Use gpt-4 encoding as default for token estimation\n+ self.encoding = tiktoken.encoding_for_model("gpt-4o-2024-08-06")\n+\n+ @OverRide\n+ async def estimate_token_count(self, prompt: str) -> int:\n+ tokens = self.encoding.encode(prompt)\n+ return len(tokens)\n+\n+\n+class OpenRouterSchematicGenerator(BaseSchematicGenerator[T]):\n+ supported_openrouter_params = ["temperature", "max_tokens"]\n+\n+ def init(\n+ self,\n+ model_name: str,\n+ logger: Logger,\n+ meter: Meter,\n+ ) -> None:\n+ super().init(logger=logger, meter=meter, model_name=model_name)\n+ self._logger = logger\n+\n+ # Build extra headers from environment variables\n+ extra_headers = {}\n+ if "OPENROUTER_HTTP_REFERER" in os.environ:\n+ extra_headers["HTTP-Referer"] = os.environ["OPENROUTER_HTTP_REFERER"]\n+ if "OPENROUTER_SITE_NAME" in os.environ:\n+ extra_headers["X-Title"] = os.environ["OPENROUTER_SITE_NAME"]\n+\n+ self._client = AsyncClient(\n+ base_url="https://openrouter.ai/api/v1\",\n+ api_key=os.environ["OPENROUTER_API_KEY"],\n+ default_headers=extra_headers if extra_headers else None,\n+ )\n+\n+ self._tokenizer = OpenRouterEstimatingTokenizer(model_name=self.model_name)\n+\n+ @Property\n+ @OverRide\n+ def id(self) -> str:\n+ return f"openrouter/{self.model_name}"\n+\n+ @Property\n+ @OverRide\n+ def tokenizer(self) -> OpenRouterEstimatingTokenizer:\n+ return self._tokenizer\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ # Default implementation - should be overridden by subclasses\n+ return 8192\n+\n+ @Policy(\n+ [\n+ retry(\n+ exceptions=(\n+ APIConnectionError,\n+ APITimeoutError,\n+ ConflictError,\n+ RateLimitError,\n+ APIResponseValidationError,\n+ ),\n+ ),\n+ retry(InternalServerError, max_exceptions=2, wait_times=(1.0, 5.0)),\n+ ]\n+ )\n+ @OverRide\n+ async def do_generate(\n+ self,\n+ prompt: str | PromptBuilder,\n+ hints: Mapping[str, Any] = {},\n+ ) -> SchematicGenerationResult[T]:\n+ if isinstance(prompt, PromptBuilder):\n+ prompt = prompt.build()\n+\n+ openrouter_api_arguments = {\n+ k: v for k, v in hints.items() if k in self.supported_openrouter_params\n+ }\n+\n+ t_start = time.time()\n+\n+ # Try with JSON mode first, but catch errors gracefully\n+ response = None\n+\n+ try:\n+ # Try with JSON mode\n+ response = await self._client.chat.completions.create(\n+ messages=[{"role": "user", "content": prompt}],\n+ model=self.model_name,\n+ response_format={"type": "json_object"},\n+ **openrouter_api_arguments,\n+ )\n+ except BadRequestError as e:\n+ # Check if it's a JSON mode error\n+ error_str = str(e)\n+ if "JSON mode" in error_str or "json_object" in error_str.lower():\n+ self._logger.error(\n+ f"\nModel '{self.model_name}' does not support JSON mode.\n"\n+ f"Please switch to a model that supports JSON mode (e.g., 'openai/gpt-4o', 'anthropic/claude-3.5-sonnet').\n"\n+ f"Attempting to continue without JSON mode enforcement, but results may be less reliable.\n"\n+ )\n+ # Retry without JSON mode with a system message to instruct JSON output\n+ try:\n+ # Add system message to instruct the model to output JSON\n+ json_instruction = "IMPORTANT: You must respond with ONLY valid JSON. No explanatory text before or after the JSON. The response must be a valid JSON object."\n+ response = await self._client.chat.completions.create(\n+ messages=[\n+ {"role": "system", "content": json_instruction},\n+ {"role": "user", "content": prompt},\n+ ],\n+ model=self.model_name,\n+ **openrouter_api_arguments,\n+ )\n+ except Exception as retry_error:\n+ self._logger.error(\n+ f"\nFailed to use model '{self.model_name}' even without JSON mode.\n"\n+ f"Error: {retry_error}\n"\n+ f"Please change your model to one that supports JSON mode or use a different model entirely.\n"\n+ )\n+ raise\n+ else:\n+ # Some other BadRequest error - just log it once and raise\n+ self._logger.error(f"OpenRouter API BadRequest: {e}")\n+ raise\n+ except RateLimitError as e:\n+ self._logger.error(\n+ f"\nRate limit exceeded for model '{self.model_name}'.\n"\n+ f"{RATE_LIMIT_ERROR_MESSAGE}\n"\n+ f"Consider:\n"\n+ f" - Using a different model\n"\n+ f" - Waiting a moment before retrying\n"\n+ f" - Adding your own API key for higher limits\n"\n+ )\n+ raise\n+ except Exception as e:\n+ self._logger.error(\n+ f"\nOpenRouter API error with model '{self.model_name}': {type(e).name}\n"\n+ f"{e}\n"\n+ f"Consider switching to a more compatible model.\n"\n+ )\n+ raise\n+\n+ t_end = time.time()\n+\n+ if response.usage:\n+ self._logger.trace(response.usage.model_dump_json(indent=2))\n+\n+ raw_content = response.choices[0].message.content or "{}"\n+\n+ # Check if we got empty response\n+ if not raw_content.strip() or raw_content.strip() == "{}":\n+ self._logger.error(\n+ f"\nModel '{self.model_name}' returned empty or invalid JSON.\n"\n+ f"Response: {raw_content}\n"\n+ f"This model may not be compatible with structured output requirements.\n"\n+ f"Please switch to a model that supports JSON mode (e.g., 'openai/gpt-4o', 'anthropic/claude-3.5-sonnet').\n"\n+ )\n+ # Set empty JSON as fallback\n+ json_content = {}\n+ else:\n+ try:\n+ json_content = json.loads(normalize_json_output(raw_content))\n+ # Check if parsed JSON is empty\n+ if not json_content or json_content == {}:\n+ self._logger.warning(\n+ "Model returned empty JSON object. Attempting to find JSON in response..."\n+ )\n+ # Try to find JSON in the response\n+ try:\n+ json_content = jsonfinder.only_json(raw_content)[2]\n+ if json_content and json_content != {}:\n+ self._logger.info(\n+ "Found valid JSON content within response."\n+ )\n+ except Exception:\n+ self._logger.error(\n+ f"Could not extract valid JSON from response: {raw_content}"\n+ )\n+ except json.JSONDecodeError as e:\n+ self._logger.warning(\n+ f"Invalid JSON returned by {self.model_name}:\n{raw_content}"\n+ )\n+ try:\n+ # Try to extract JSON using jsonfinder\n+ json_content = jsonfinder.only_json(raw_content)[2]\n+ self._logger.warning(\n+ "Found JSON content within model response; continuing..."\n+ )\n+ except Exception as finder_error:\n+ self._logger.error(\n+ f"\nCould not parse JSON from model response.\n"\n+ f"Raw response: {raw_content}\n"\n+ f"Error: {finder_error}\n"\n+ f"Model '{self.model_name}' may not be compatible.\n"\n+ f"Consider switching to a model that supports structured output.\n"\n+ )\n+ json_content = {}\n+\n+ try:\n+ content = self.schema.model_validate(json_content)\n+\n+ assert response.usage\n+\n+ return SchematicGenerationResult(\n+ content=content,\n+ info=GenerationInfo(\n+ schema_name=self.schema.name,\n+ model=self.id,\n+ duration=(t_end - t_start),\n+ usage=UsageInfo(\n+ input_tokens=response.usage.prompt_tokens,\n+ output_tokens=response.usage.completion_tokens,\n+ extra={\n+ "cached_input_tokens": getattr(\n+ response.usage,\n+ "prompt_cache_hit_tokens",\n+ 0,\n+ )\n+ },\n+ ),\n+ ),\n+ )\n+ except ValidationError as e:\n+ self._logger.error(\n+ f"\nJSON content returned by '{self.model_name}' does not match expected schema.\n"\n+ f"Schema: {self.schema.name}\n"\n+ f"Raw response: {raw_content}\n"\n+ f"Parsed JSON: {json.dumps(json_content, indent=2) if json_content else 'Empty'}\n"\n+ f"Validation errors: {str(e)}\n"\n+ f"This model may not be producing valid structured output.\n"\n+ f"Consider switching to a model that supports JSON mode.\n"\n+ )\n+ raise\n+\n+\n+class OpenRouterGPT4O(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(model_name="openai/gpt-4o", logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 128 * 1024\n+\n+\n+class OpenRouterGPT4OMini(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(model_name="openai/gpt-4o-mini", logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 128 * 1024\n+\n+\n+class OpenRouterClaude35Sonnet(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(\n+ model_name="anthropic/claude-3.5-sonnet", logger=logger, meter=meter\n+ )\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 8192\n+\n+\n+class OpenRouterLlama33_70B(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(\n+ model_name="meta-llama/llama-3.3-70b-instruct", logger=logger, meter=meter\n+ )\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 8192\n+\n+\n+class OpenRouterEmbedder(BaseEmbedder):\n+ supported_arguments = ["dimensions"]\n+\n+ # Known embedding model dimensions\n+ _KNOWN_DIMENSIONS: dict[str, int] = {\n+ "openai/text-embedding-3-large": 3072,\n+ "openai/text-embedding-3-small": 1536,\n+ "openai/text-embedding-ada-002": 1536,\n+ "qwen/qwen3-embedding-8b": 4096,\n+ "qwen/qwen-embedding-v2": 1536,\n+ }\n+\n+ def init(self, model_name: str, logger: Logger, meter: Meter) -> None:\n+ super().init(logger, meter, model_name)\n+ self.model_name = model_name\n+\n+ # Build extra headers from environment variables\n+ extra_headers = {}\n+ if "OPENROUTER_HTTP_REFERER" in os.environ:\n+ extra_headers["HTTP-Referer"] = os.environ["OPENROUTER_HTTP_REFERER"]\n+ if "OPENROUTER_SITE_NAME" in os.environ:\n+ extra_headers["X-Title"] = os.environ["OPENROUTER_SITE_NAME"]\n+\n+ self._client = AsyncClient(\n+ base_url="https://openrouter.ai/api/v1\",\n+ api_key=os.environ["OPENROUTER_API_KEY"],\n+ default_headers=extra_headers if extra_headers else None,\n+ )\n+ self._tokenizer = OpenRouterEstimatingTokenizer(model_name=self.model_name)\n+ # Cache dimensions after first API call if not known\n+ self._cached_dimensions: int | None = None\n+\n+ @Property\n+ @OverRide\n+ def id(self) -> str:\n+ return f"openrouter/{self.model_name}"\n+\n+ @Property\n+ @OverRide\n+ def tokenizer(self) -> OpenRouterEstimatingTokenizer:\n+ return self._tokenizer\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ # Default max tokens for embedding models\n+ return 8192\n+\n+ @Property\n+ @OverRide\n+ def dimensions(self) -> int:\n+ # Check environment variable override first\n+ if "OPENROUTER_EMBEDDER_DIMENSIONS" in os.environ:\n+ return int(os.environ["OPENROUTER_EMBEDDER_DIMENSIONS"])\n+\n+ # Return cached dimensions if available\n+ if self._cached_dimensions is not None:\n+ return self._cached_dimensions\n+\n+ # Check known dimensions lookup\n+ for model_key, dims in self._KNOWN_DIMENSIONS.items():\n+ if model_key in self.model_name:\n+ return dims\n+\n+ # Default fallback - most embedding models use 1536 or 3072\n+ # This will be updated after first API call\n+ return 1536\n+\n+ @Policy(\n+ [\n+ retry(\n+ exceptions=(\n+ APIConnectionError,\n+ APITimeoutError,\n+ ConflictError,\n+ RateLimitError,\n+ APIResponseValidationError,\n+ ),\n+ ),\n+ retry(InternalServerError, max_exceptions=2, wait_times=(1.0, 5.0)),\n+ ]\n+ )\n+ @OverRide\n+ async def do_embed(\n+ self,\n+ texts: list[str],\n+ hints: Mapping[str, Any] = {},\n+ ) -> EmbeddingResult:\n+ filtered_hints = {\n+ k: v for k, v in hints.items() if k in self.supported_arguments\n+ }\n+ try:\n+ response = await self._client.embeddings.create(\n+ model=self.model_name,\n+ input=texts,\n+ **filtered_hints,\n+ )\n+ except RateLimitError:\n+ self.logger.error(\n+ f"\nRate limit exceeded for embedder model '{self.model_name}'.\n"\n+ f"{RATE_LIMIT_ERROR_MESSAGE}\n"\n+ f"Consider:\n"\n+ f" - Using a different embedder model\n"\n+ f" - Waiting a moment before retrying\n"\n+ f" - Adding your own API key for higher limits\n"\n+ )\n+ raise\n+\n+ vectors = [data_point.embedding for data_point in response.data]\n+\n+ # Cache dimensions from first response if not already cached and not in known list\n+ if self._cached_dimensions is None and vectors:\n+ actual_dims = len(vectors[0])\n+ # Only cache if different from default or if not found in known dimensions\n+ if actual_dims != 1536 or not any(\n+ key in self.model_name for key in self._KNOWN_DIMENSIONS\n+ ):\n+ self._cached_dimensions = actual_dims\n+ self.logger.debug(\n+ f"Detected embedding dimensions for '{self.model_name}': {actual_dims}"\n+ )\n+\n+ return EmbeddingResult(vectors=vectors)\n+\n+\n+class OpenRouterTextEmbedding3Large(OpenRouterEmbedder):\n+ def init(self, logger: Logger, meter: Meter) -> None:\n+ super().init(\n+ model_name="openai/text-embedding-3-large", logger=logger, meter=meter\n+ )\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return 8192\n+\n+ @Property\n+ @OverRide\n+ def dimensions(self) -> int:\n+ return 3072\n+\n+\n+class OpenRouterService(NLPService):\n+ @staticmethod\n+ def verify_environment() -> str | None:\n+ """Returns an error message if the environment is not set up correctly."""\n+\n+ if not os.environ.get("OPENROUTER_API_KEY"):\n+ return """\\n+You're using the OpenRouter NLP service, but OPENROUTER_API_KEY is not set.\n+Please set OPENROUTER_API_KEY in your environment before running Parlant.\n+"""\n+\n+ return None\n+\n+ def init(\n+ self,\n+ logger: Logger,\n+ meter: Meter,\n+ ) -> None:\n+ self._logger = logger\n+ self._meter = meter\n+ self._logger.info("Initialized OpenRouterService")\n+ # Get model_name from environment variable\n+ self.model_name = os.environ.get(\n+ "OPENROUTER_MODEL", "openai/gpt-4o"\n+ )\n+ # Get embedder_model_name from environment variable\n+ self.embedder_model_name = os.environ.get(\n+ "OPENROUTER_EMBEDDER_MODEL", "openai/text-embedding-3-large"\n+ )\n+ self._logger.info(f"OpenRouter model name: {self.model_name}")\n+ self._logger.info(f"OpenRouter embedder model name: {self.embedder_model_name}")\n+\n+ # Create dynamic embedder class that can be resolved from the container\n+ # This captures embedder_model_name in a closure so the container can resolve it\n+ embedder_model = self.embedder_model_name\n+\n+ class DynamicOpenRouterEmbedder(OpenRouterEmbedder):\n+ def init(self, logger: Logger, meter: Meter):\n+ super().init(model_name=embedder_model, logger=logger, meter=meter)\n+\n+ self._dynamic_embedder_class = DynamicOpenRouterEmbedder\n+\n+ def _get_specialized_generator_class(\n+ self,\n+ model_name: str,\n+ t: type[T],\n+ ) -> Callable[[Logger, Meter], OpenRouterSchematicGenerator[T]]:\n+ """\n+ Returns the specialized generator class for known models.\n+ For unknown models, creates a dynamic generator that works with any OpenRouter model.\n+ """\n+ model_mapping: dict[\n+ str, Callable[[Logger, Meter], OpenRouterSchematicGenerator[T]]\n+ ] = {\n+ "openai/gpt-4o": lambda logger, meter: OpenRouterGPT4O[t](logger, meter), # type: ignore\n+ "openai/gpt-4o-mini": lambda logger, meter: OpenRouterGPT4OMini[t](logger, meter), # type: ignore\n+ "anthropic/claude-3.5-sonnet": lambda logger, meter: OpenRouterClaude35Sonnet[t](logger, meter), # type: ignore\n+ "meta-llama/llama-3.3-70b-instruct": lambda logger, meter: OpenRouterLlama33_70B[t](logger, meter), # type: ignore\n+ }\n+\n+ # Check if we have a predefined generator for this model\n+ if generator_factory := model_mapping.get(model_name):\n+ return generator_factory\n+\n+ # Create a dynamic generator for any OpenRouter model\n+ # Get max_tokens from environment variable or use sensible defaults based on model name\n+ max_tokens_str = os.environ.get("OPENROUTER_MAX_TOKENS")\n+ if max_tokens_str:\n+ max_tokens = int(max_tokens_str)\n+ else:\n+ # Provide sensible defaults based on model family\n+ if "gpt-4" in model_name:\n+ max_tokens = 128 * 1024\n+ elif "claude" in model_name:\n+ max_tokens = 8192\n+ elif "llama" in model_name or "gemma" in model_name:\n+ max_tokens = 8192\n+ else:\n+ max_tokens = 8192 # Safe default for unknown models\n+\n+ # Create dynamic generator class with the specific max_tokens\n+ final_max_tokens = max_tokens\n+\n+ class DynamicOpenRouterGenerator(OpenRouterSchematicGenerator[T]):\n+ def init(self, logger: Logger, meter: Meter):\n+ super().init(model_name=model_name, logger=logger, meter=meter)\n+\n+ @Property\n+ @OverRide\n+ def max_tokens(self) -> int:\n+ return final_max_tokens\n+\n+ # Return a factory function that creates the properly typed instance\n+ def create_generator(\n+ logger: Logger, meter: Meter\n+ ) -> OpenRouterSchematicGenerator[T]:\n+ return DynamicOpenRouterGenerator[t](logger, meter) # type: ignore\n+\n+ return create_generator\n+\n+ @OverRide\n+ async def get_schematic_generator(\n+ self, t: type[T]\n+ ) -> OpenRouterSchematicGenerator[T]:\n+ generator_factory = self._get_specialized_generator_class(self.model_name, t)\n+ return generator_factory(self._logger, self._meter)\n+\n+ @OverRide\n+ async def get_embedder(self) -> Embedder:\n+ # Use OpenRouter embedder with the configured embedder model name\n+ # Default to text-embedding-3-large if not specified\n+ if self.embedder_model_name == "openai/text-embedding-3-large":\n+ return OpenRouterTextEmbedding3Large(logger=self._logger, meter=self._meter)\n+ else:\n+ # Return instance of dynamic embedder class that can be resolved from container\n+ return self._dynamic_embedder_class(logger=self._logger, meter=self._meter)\n+\n+ @OverRide\n+ async def get_moderation_service(self) -> ModerationService:\n+ return NoModeration()\ndiff --git a/src/parlant/sdk.py b/src/parlant/sdk.py\nindex e5ab96af1..5ec5b3a37 100644\n--- a/src/parlant/sdk.py\n+++ b/src/parlant/sdk.py\n@@ -408,6 +408,30 @@ def fireworks(container: Container) -> NLPService:\n \n return FireworksService(container[Logger], container[Meter])\n \n+ @staticmethod\n+ def openrouter(\n+ container: Container | None = None,\n+ ) -> NLPService | Callable[[Container], NLPService]:\n+ """\n+ Returns a callable that creates an OpenRouter NLPService instance using the provided container.\n+ If container is None, the callable expects the container to be provided later (by the Server).\n+ All configuration is done via environment variables.\n+ """\n+ from parlant.adapters.nlp.openrouter_service import OpenRouterService\n+\n+ def factory(c: Container) -> NLPService:\n+ if error := OpenRouterService.verify_environment():\n+ raise SDKError(error)\n+ return OpenRouterService(\n+ c[Logger],\n+ c[Meter],\n+ )\n+\n+ if container is not None:\n+ return factory(container)\n+\n+ return factory\n+\n \n class _CachedGuidelineEvaluation(TypedDict, total=False):\n id: ObjectId\ndiff --git a/tests/adapters/nlp/test_openrouter_service.py b/tests/adapters/nlp/test_openrouter_service.py\nnew file mode 100644\nindex 000000000..22d641986\n--- /dev/null\n+++ b/tests/adapters/nlp/test_openrouter_service.py\n@@ -0,0 +1,420 @@\n+# Copyright 2025 Emcie Co Ltd.\n+#\n+# Licensed under the Apache License, Version 2.0 (the "License");\n+# you may not use this file except in compliance with the License.\n+# You may obtain a copy of the License at\n+#\n+# http://www.apache.org/licenses/LICENSE-2.0\n+#\n+# Unless required by applicable law or agreed to in writing, software\n+# distributed under the License is distributed on an "AS IS" BASIS,\n+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n+# See the License for the specific language governing permissions and\n+# limitations under the License.\n+\n+import os\n+from lagom import Container\n+import pytest\n+from unittest.mock import AsyncMock, patch, Mock\n+import asyncio\n+from openai.types.chat import ChatCompletion, ChatCompletionMessage\n+from openai.types.chat.chat_completion import Choice\n+from openai.types.completion_usage import CompletionUsage\n+\n+from parlant.adapters.nlp.openrouter_service import ( # type: ignore[reportMissingImports]\n+ OpenRouterService,\n+ OpenRouterSchematicGenerator,\n+ OpenRouterGPT4O,\n+ OpenRouterGPT4OMini,\n+ OpenRouterClaude35Sonnet,\n+ OpenRouterLlama33_70B,\n+ OpenRouterEstimatingTokenizer,\n+)\n+from parlant.core.loggers import Logger\n+from parlant.core.common import DefaultBaseModel\n+from parlant.core.meter import Meter\n+\n+\n+class SchemaData(DefaultBaseModel):\n+ """Test schema for type checking."""\n+\n+ test_field: str = "test_value"\n+\n+\n+@pytest.fixture(autouse=True)\n+def set_api_keys():\n+ """Set API keys for tests that use container fixture."""\n+ # Container fixture initializes ServiceRegistry which requires OPENAI_API_KEY\n+ # OpenRouter tests also need OPENROUTER_API_KEY\n+ with patch.dict(\n+ os.environ,\n+ {\n+ "OPENAI_API_KEY": "test-openai-key",\n+ "OPENROUTER_API_KEY": "test-openrouter-key",\n+ },\n+ clear=False,\n+ ):\n+ yield\n+\n+\n+def test_that_missing_openrouter_api_key_returns_error_message() -> None:\n+ """Test that missing OPENROUTER_API_KEY returns error message."""\n+ with patch.dict(os.environ, {}, clear=True):\n+ error = OpenRouterService.verify_environment()\n+ assert error is not None\n+ assert "OPENROUTER_API_KEY is not set" in error\n+\n+\n+def test_that_present_api_key_returns_none() -> None:\n+ """Test that present API key returns None (success)."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ error = OpenRouterService.verify_environment()\n+ assert error is None\n+\n+\n+def test_that_openrouter_service_initializes_with_default_model() -> None:\n+ """Test OpenRouterService initialization with default model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(logger=mock_logger, meter=mock_meter)\n+ assert service.model_name == "openai/gpt-4o"\n+\n+\n+def test_that_openrouter_service_initializes_with_custom_model() -> None:\n+ """Test OpenRouterService initialization with custom model from environment."""\n+ with patch.dict(\n+ os.environ,\n+ {\n+ "OPENROUTER_API_KEY": "test-key",\n+ "OPENROUTER_MODEL": "anthropic/claude-3.5-sonnet",\n+ },\n+ clear=True,\n+ ):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(logger=mock_logger, meter=mock_meter)\n+ assert service.model_name == "anthropic/claude-3.5-sonnet"\n+\n+\n+def test_that_openrouter_service_uses_environment_model() -> None:\n+ """Test OpenRouterService uses OPENROUTER_MODEL from environment."""\n+ with patch.dict(\n+ os.environ,\n+ {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MODEL": "meta-llama/llama-3.3-70b-instruct"},\n+ clear=True,\n+ ):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(logger=mock_logger, meter=mock_meter)\n+ assert service.model_name == "meta-llama/llama-3.3-70b-instruct"\n+\n+\n+def test_that_openrouter_service_respects_custom_max_tokens() -> None:\n+ """Test OpenRouterService respects max_tokens from environment variable."""\n+ with patch.dict(\n+ os.environ,\n+ {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MAX_TOKENS": "4096"},\n+ clear=True,\n+ ):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ service = OpenRouterService(logger=mock_logger, meter=mock_meter)\n+ # max_tokens is used when creating generators, not stored in service\n+ assert service.model_name == "openai/gpt-4o" # Default model\n+\n+\n+def test_that_openrouter_estimating_tokenizer_works(container: Container) -> None:\n+ """Test OpenRouterEstimatingTokenizer token estimation."""\n+ tokenizer = OpenRouterEstimatingTokenizer(model_name="openai/gpt-4o")\n+ tokens = asyncio.run(tokenizer.estimate_token_count("Hello world"))\n+ assert tokens > 0\n+\n+\n+def test_that_openrouter_gpt4o_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterGPT4O initialization."""\n+ generator = OpenRouterGPT4O[SchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "openai/gpt-4o"\n+ assert generator.id == "openrouter/openai/gpt-4o"\n+ assert generator.max_tokens == 128 * 1024\n+\n+\n+def test_that_openrouter_gpt4o_mini_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterGPT4OMini initialization."""\n+ generator = OpenRouterGPT4OMini[SchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "openai/gpt-4o-mini"\n+ assert generator.max_tokens == 128 * 1024\n+\n+\n+def test_that_openrouter_claude_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterClaude35Sonnet initialization."""\n+ generator = OpenRouterClaude35Sonnet[SchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "anthropic/claude-3.5-sonnet"\n+ assert generator.max_tokens == 8192\n+\n+\n+def test_that_openrouter_llama_generator_initializes_correctly(container: Container) -> None:\n+ """Test OpenRouterLlama33_70B initialization."""\n+ generator = OpenRouterLlama33_70B[SchemaData](logger=container[Logger], meter=container[Meter])\n+ assert generator.model_name == "meta-llama/llama-3.3-70b-instruct"\n+ assert generator.max_tokens == 8192\n+\n+\n+@patch("parlant.adapters.nlp.openrouter_service.AsyncClient")\n+def test_that_openrouter_generator_sets_custom_headers(mock_client_class) -> None:\n+ """Test that OpenRouter generator sets custom headers from environment."""\n+ with patch.dict(\n+ os.environ,\n+ {\n+ "OPENROUTER_API_KEY": "test-key",\n+ "OPENROUTER_HTTP_REFERER": "https://example.com\",\n+ "OPENROUTER_SITE_NAME": "My App",\n+ },\n+ clear=True,\n+ ):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ generator = OpenRouterSchematicGenerator[SchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=mock_logger,\n+ meter=mock_meter,\n+ )\n+\n+ # Verify client was called with headers\n+ mock_client_class.assert_called_once()\n+ call_args = mock_client_class.call_args\n+ assert "default_headers" in call_args[1]\n+ assert call_args[1]["default_headers"]["HTTP-Referer"] == "https://example.com\"\n+ assert call_args[1]["default_headers"]["X-Title"] == "My App"\n+\n+\n+@patch("parlant.adapters.nlp.openrouter_service.AsyncClient")\n+def test_that_openrouter_generator_without_custom_headers(mock_client_class) -> None:\n+ """Test OpenRouter generator without custom headers."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+ generator = OpenRouterSchematicGenerator[SchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=mock_logger,\n+ meter=mock_meter,\n+ )\n+\n+ # Verify client was called without custom headers\n+ mock_client_class.assert_called_once()\n+ call_args = mock_client_class.call_args\n+ assert call_args[1]["default_headers"] is None\n+\n+\n+@patch("parlant.adapters.nlp.openrouter_service.AsyncClient")\n+async def test_that_openrouter_generator_handles_json_mode_error(mock_client_class) -> None:\n+ """Test that OpenRouter generator handles JSON mode errors gracefully."""\n+ mock_client = AsyncMock()\n+ mock_client_class.return_value = mock_client\n+\n+ # Mock BadRequestError for JSON mode\n+ from openai import BadRequestError\n+\n+ mock_client.chat.completions.create.side_effect = BadRequestError(\n+ "Model does not support JSON mode", body={"error": {"message": "JSON mode error"}}, response=Mock()\n+ )\n+\n+ mock_logger = Mock()\n+ mock_meter = Mock()\n+\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=False):\n+ generator = OpenRouterSchematicGenerator[SchemaData](\n+ model_name="test-model",\n+ logger=mock_logger,\n+ meter=mock_meter,\n+ )\n+\n+ # Should fail since we're mocking the error\n+ with pytest.raises(BadRequestError):\n+ await generator.do_generate("Test prompt")\n+\n+\n+async def test_that_openrouter_generator_handles_successful_response(\n+ container: Container,\n+) -> None:\n+ """Test OpenRouter generator with successful JSON response."""\n+ mock_response = Mock(spec=ChatCompletion)\n+ mock_response.choices = [\n+ Choice(\n+ message=ChatCompletionMessage(role="assistant", content='{"test_field": "test_value"}'),\n+ finish_reason="stop",\n+ index=0,\n+ )\n+ ]\n+ mock_response.usage = CompletionUsage(\n+ prompt_tokens=10, completion_tokens=20, total_tokens=30\n+ )\n+\n+ with patch("parlant.adapters.nlp.openrouter_service.AsyncClient") as mock_client_class:\n+ mock_client = AsyncMock()\n+ mock_client.chat.completions.create = AsyncMock(return_value=mock_response)\n+ mock_client_class.return_value = mock_client\n+\n+ generator = OpenRouterSchematicGenerator[SchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ )\n+\n+ result = await generator.do_generate('Generate {"test_field": "test_value"}')\n+\n+ assert result.content.test_field == "test_value"\n+ assert result.info.usage.input_tokens == 10\n+ assert result.info.usage.output_tokens == 20\n+\n+\n+def test_that_openrouter_service_returns_correct_generator(container: Container) -> None:\n+ """Test OpenRouterService.get_schematic_generator with default model."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert isinstance(generator, OpenRouterSchematicGenerator)\n+ assert generator.model_name == "openai/gpt-4o"\n+\n+\n+def test_that_openrouter_service_returns_correct_generator_for_claude(\n+ container: Container,\n+) -> None:\n+ """Test OpenRouterService.get_schematic_generator with Claude model."""\n+ with patch.dict(\n+ os.environ,\n+ {\n+ "OPENROUTER_API_KEY": "test-key",\n+ "OPENROUTER_MODEL": "anthropic/claude-3.5-sonnet",\n+ },\n+ clear=True,\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert isinstance(generator, OpenRouterClaude35Sonnet)\n+ assert generator.model_name == "anthropic/claude-3.5-sonnet"\n+\n+\n+def test_that_openrouter_service_creates_dynamic_generator_for_unknown_model(\n+ container: Container,\n+) -> None:\n+ """Test OpenRouterService creates dynamic generator for unknown model."""\n+ with patch.dict(\n+ os.environ,\n+ {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MODEL": "custom/model-name"},\n+ clear=True,\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert isinstance(generator, OpenRouterSchematicGenerator)\n+ assert generator.model_name == "custom/model-name"\n+\n+\n+def test_that_openrouter_service_uses_custom_max_tokens(container: Container) -> None:\n+ """Test OpenRouterService uses max_tokens from environment for unknown model."""\n+ with patch.dict(\n+ os.environ,\n+ {\n+ "OPENROUTER_API_KEY": "test-key",\n+ "OPENROUTER_MODEL": "custom/model",\n+ "OPENROUTER_MAX_TOKENS": "2048",\n+ },\n+ clear=True,\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert generator.max_tokens == 2048\n+\n+\n+def test_that_openrouter_service_uses_environment_max_tokens(container: Container) -> None:\n+ """Test OpenRouterService uses environment max_tokens for unknown model."""\n+ with patch.dict(\n+ os.environ,\n+ {\n+ "OPENROUTER_API_KEY": "test-key",\n+ "OPENROUTER_MODEL": "custom/unknown-model",\n+ "OPENROUTER_MAX_TOKENS": "4096",\n+ },\n+ clear=True,\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert generator.max_tokens == 4096\n+\n+\n+def test_that_openrouter_service_sets_default_max_tokens_for_gpt4(container: Container) -> None:\n+ """Test OpenRouterService sets default max_tokens for GPT-4 models."""\n+ with patch.dict(\n+ os.environ,\n+ {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MODEL": "openai/gpt-4-turbo"},\n+ clear=True,\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert generator.max_tokens == 128 * 1024\n+\n+\n+def test_that_openrouter_service_sets_default_max_tokens_for_claude(container: Container) -> None:\n+ """Test OpenRouterService sets default max_tokens for Claude models."""\n+ with patch.dict(\n+ os.environ,\n+ {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MODEL": "anthropic/claude-2"},\n+ clear=True,\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert generator.max_tokens == 8192\n+\n+\n+def test_that_openrouter_service_sets_default_max_tokens_for_llama(container: Container) -> None:\n+ """Test OpenRouterService sets default max_tokens for Llama models."""\n+ with patch.dict(\n+ os.environ,\n+ {"OPENROUTER_API_KEY": "test-key", "OPENROUTER_MODEL": "meta-llama/llama-2-70b"},\n+ clear=True,\n+ ):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ generator = asyncio.run(service.get_schematic_generator(SchemaData))\n+ assert generator.max_tokens == 8192\n+\n+\n+@pytest.mark.skip(reason="Requires network access - embedder initialization may use JinaAIEmbedder fallback")\n+def test_that_openrouter_service_returns_openrouter_embedder(container: Container) -> None:\n+ """Test OpenRouterService returns OpenRouter embedder.\n+ \n+ Note: This test is skipped because the embedder initialization may require network access\n+ if the installed version uses a JinaAIEmbedder fallback.\n+ """\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ embedder = asyncio.run(service.get_embedder())\n+ # OpenRouter embedder should be returned\n+ from parlant.adapters.nlp.openrouter_service import (\n+ OpenRouterEmbedder,\n+ OpenRouterTextEmbedding3Large,\n+ )\n+ # Should be either OpenRouterEmbedder or OpenRouterTextEmbedding3Large\n+ assert isinstance(embedder, (OpenRouterEmbedder, OpenRouterTextEmbedding3Large))\n+ assert embedder is not None\n+\n+\n+def test_that_openrouter_service_returns_no_moderation(container: Container) -> None:\n+ """Test OpenRouterService returns NoModeration."""\n+ with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}, clear=True):\n+ service = OpenRouterService(logger=container[Logger], meter=container[Meter])\n+ moderation = asyncio.run(service.get_moderation_service())\n+ from parlant.core.nlp.moderation import NoModeration\n+ assert isinstance(moderation, NoModeration)\n+\n+\n+def test_that_openrouter_generator_supports_correct_parameters(container: Container) -> None:\n+ """Test supported OpenRouter parameters."""\n+ generator = OpenRouterSchematicGenerator[SchemaData](\n+ model_name="openai/gpt-4o",\n+ logger=container[Logger],\n+ meter=container[Meter],\n+ )\n+\n+ expected_params = ["temperature", "max_tokens"]\n+ assert generator.supported_openrouter_params == expected_params\n+\n", "metadata": {"problem_domain": "New Feature Additions", "difficulty": "high", "estimated_review_effort": 4}}

[luanzhiwow]

{"instance_id": "github__spec-kit-1002@9809b1a", "repo": "github/spec-kit", "language": "Python", "pull_number": 1002, "title": "docs: add steps for testing template and command changes locally", "body": "Closes #729 \r\n\r\n## Summary\r\n\r\nAdd section documenting how to test template and command changes locally. This PR is based on a helpful comment by @localden which helped me. Opening this PR to share this knowledge with other contributors who may encounter the same workflow challenge.\r\n\r\n## Test plan\r\n\r\n - [x] Verified documentation accuracy against current workflow\r\n - [x] Confirmed script paths exist and are correct\r\n - [x] Tested local package generation process\r\n\r\n## Details\r\n\r\nThe change adds a new "Testing template and command changes locally" subsection under the Development workflow section that explains:\r\n\r\n 1. The Problem: Running uv run specify init pulls released packages which don't include local changes\r\n 2. The Solution: Creating packages locally, copying them them over and testing them\r\n", "created_at": "2025-10-22T02:23:38Z", "problem_statement": "How can I test local template/command changes without creating a release?\nI am trying to add a new command to spec-kit (see #723), but I am not able to figure out how to test it locally. I went through all your documentation and tried follow instructions in docs/local-development.md.\n\nWhen I run specify init, it always downloads templates from the latest GitHub release (via download_template_from_github()), so my local changes are never picked up:\n- Changes to templates/commands/*.md are ignored\n- Modified scripts in scripts/bash/ or scripts/powershell/ aren't used\n- Updates to memory/ files aren't included\n\nFor #723, I eventually had to manually copy files after running specify init to test the new /cross-feature command, which was tedious and error-prone. Please correct me if I am wrong.\n\n## Proposed Solution\n\nWould it make sense to add a --local flag to specify init that uses local files instead of downloading from GitHub?\n\nspecify init test-project --ai claude --local\n\nThis would enable proper local testing without manual workarounds.\n\nIf this sounds good, I will be happy to implement this feature and submit a PR. Let me know if you prefer a different approach or have any design considerations I should account for.", "hints_text": "Hello,\n\nI have opened PR #941 to address this issue. It takes a lower-impact approach than the one proposed in the issue description above. Please take a look when you have a moment and share any feedback.\n\nThanks!", "resolved_issues": [{"number": 729, "title": "How can I test local template/command changes without creating a release?", "body": "I am trying to add a new command to spec-kit (see #723), but I am not able to figure out how to test it locally. I went through all your documentation and tried follow instructions in docs/local-development.md.\n\nWhen I run specify init, it always downloads templates from the latest GitHub release (via download_template_from_github()), so my local changes are never picked up:\n- Changes to templates/commands/*.md are ignored\n- Modified scripts in scripts/bash/ or scripts/powershell/ aren't used\n- Updates to memory/ files aren't included\n\nFor #723, I eventually had to manually copy files after running specify init to test the new /cross-feature command, which was tedious and error-prone. Please correct me if I am wrong.\n\n## Proposed Solution\n\nWould it make sense to add a --local flag to specify init that uses local files instead of downloading from GitHub?\n\nspecify init test-project --ai claude --local\n\nThis would enable proper local testing without manual workarounds.\n\nIf this sounds good, I will be happy to implement this feature and submit a PR. Let me know if you prefer a different approach or have any design considerations I should account for."}], "base_commit": "9f123e013a747558925ecac435f0a225f2dc1e50", "commit_to_review": {"head_commit": "9809b1a4abb4252ffca964f324dc276cbdf298cf", "head_commit_message": "docs: add steps for testing template and command changes locally", "patch_to_review": "diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md\nindex 3e6e24aa8..58447f756 100644\n--- a/CONTRIBUTING.md\n+++ b/CONTRIBUTING.md\n@@ -62,6 +62,28 @@ When working on spec-kit:\n 3. Test script functionality in the scripts/ directory\n 4. Ensure memory files (memory/constitution.md) are updated if major process changes are made\n \n+### Testing template and command changes locally\n+\n+Running uv run specify init pulls released packages, which won\u2019t include your local changes. \n+To test your templates, commands, and other changes locally, follow these steps:\n+\n+1. Create release packages\n+\n+ Run the following command to generate the local packages:\n+ \n+ ./.github/workflows/scripts/create-release-packages.sh v1.0.0\n+ \n+\n+2. Copy the relevant package to your test project\n+\n+ \n+ cp -r .genreleases/sdd-copilot-package-sh/. /PATH_TO/test-project/\n+ \n+\n+3. Open and test the agent\n+\n+ Navigate to your test project folder and open the agent to verify your implementation.\n+\n ## AI contributions in Spec Kit\n \n > [!IMPORTANT]\n"}, "reference_review_comments": [{"text": "@user1:\n[nitpick] The placeholder /PATH_TO/test-project/ should be more descriptive. Consider changing it to <path-to-test-project> to follow common documentation conventions for placeholders.\nsuggestion\n cp -r .genreleases/sdd-copilot-package-sh/. <path-to-test-project>/\n", "path": "CONTRIBUTING.md", "diff_hunk": "@@ -62,6 +62,28 @@ When working on spec-kit:\n 3. Test script functionality in the scripts/ directory\n 4. Ensure memory files (memory/constitution.md) are updated if major process changes are made\n \n+### Testing template and command changes locally\n+\n+Running uv run specify init pulls released packages, which won\u2019t include your local changes. \n+To test your templates, commands, and other changes locally, follow these steps:\n+\n+1. Create release packages\n+\n+ Run the following command to generate the local packages:\n+ \n+ ./.github/workflows/scripts/create-release-packages.sh v1.0.0\n+ \n+\n+2. Copy the relevant package to your test project\n+\n+ \n+ cp -r .genreleases/sdd-copilot-package-sh/. /PATH_TO/test-project/", "line": null, "start_line": null, "original_line": 80, "original_start_line": null}], "merged_commit": "89f5f9c0b97805534a89b95666b4f383b2f01749", "merged_patch": "diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md\nindex 3e6e24aa8..e5897b383 100644\n--- a/CONTRIBUTING.md\n+++ b/CONTRIBUTING.md\n@@ -62,6 +62,28 @@ When working on spec-kit:\n 3. Test script functionality in the `scripts/` directory\n 4. Ensure memory files (`memory/constitution.md`) are updated if major process changes are made\n \n+### Testing template and command changes locally\n+\n+Running `uv run specify init` pulls released packages, which won\u2019t include your local changes. \n+To test your templates, commands, and other changes locally, follow these steps:\n+\n+1. **Create release packages**\n+\n+ Run the following command to generate the local packages:\n+ \n+ ./.github/workflows/scripts/create-release-packages.sh v1.0.0\n+ \n+\n+2. **Copy the relevant package to your test project**\n+\n+ \n+ cp -r .genreleases/sdd-copilot-package-sh/. /\n+ \n+\n+3. **Open and test the agent**\n+\n+ Navigate to your test project folder and open the agent to verify your implementation.\n+\n ## AI contributions in Spec Kit\n \n > [!IMPORTANT]\n", "metadata": {"problem_domain": "New Feature Additions", "difficulty": "low", "estimated_review_effort": 2}} {"instance_id": "github__spec-kit-986@392f8b7", "repo": "github/spec-kit", "language": "Python", "pull_number": 986, "title": "(feat): Enhancements to Spec Kit", "body": "## Description\r\n\r\n- Introduces a smoother hand-off between stages when used with GitHub Copilot in Visual Studio Code. Prompts are now effectively \"shortcuts\" for chat modes, and chat modes can then hand-off to specific post-production steps.\r\n- Adds support for the `version` command. (#486)\r\n- Fixes #975\r\n- Fixes #970 \r\n\r\n## Screenshots\r\n\r\n### Hand-offs\r\n\r\n<img width=\"1138\" height=\"356\" alt=\"image\" src=\"https://github.com/user-attachments/assets/cdd33d9a-0c5b-4638-bd0c-2677ac6b3a98\" />\r\n\r\n<img width=\"1119\" height=\"481\" alt=\"image\" src=\"https://github.com/user-attachments/assets/fb3b7718-b806-4186-ac68-f249711d960d\" />\r\n\r\n### Version\r\n\r\n<img width=\"3800\" height=\"677\" alt=\"image\" src=\"https://github.com/user-attachments/assets/6c41a1a5-56e7-43b6-9b99-0f071e6d190e\" />\r\n\r\n\r\n## References\r\n\r\n- https://github.com/microsoft/vscode/issues/261542\r\n- https://github.com/microsoft/vscode/issues/272211\r\n\r\n## Behavior notes\r\n\r\n- There is an unexpected behavior when hand-off occurs, resetting to **Agent Mode**. This will be fixed by the VS Code team.", "created_at": "2025-10-21T17:28:23Z", "problem_statement": "Add graceful fallback and logging for GitHub API rate-limiting during template fetch\nProblem\n- `specify init` fetches release data and downloads assets from the GitHub Releases API. If the API rate-limits (or returns an unexpected status), the current error output can be terse and does not expose helpful headers like `X-RateLimit-Remaining`, `X-RateLimit-Reset`, or the `Retry-After` header. This makes diagnosing transient network or rate-limit issues harder for users and maintainers.\n\nWhy this helps\n- Displaying the relevant GitHub rate-limit headers and providing a sensible fallback makes failures easier to understand and act on. A fallback can also attempt a short backoff/retry for transient rate-limits and print the time when the client can retry based on `X-RateLimit-Reset`.\n\nProposed change\n1. Add header-aware error reporting in `download_template_from_github` (or the HTTP helper used) so that when a non-200 response is received, the error panel includes:\n - `status_code` and brief reason (already present)\n - `X-RateLimit-Limit` (if present)\n - `X-RateLimit-Remaining` (if present)\n - `X-RateLimit-Reset` (if present)-convert epoch seconds to a human-readable timestamp in the user's local timezone\n - `Retry-After` (if present)\n\n2. If the response status indicates rate limiting (HTTP 429) or `X-RateLimit-Remaining` is `0`, implement a simple optional retry strategy:\n - If `Retry-After` exists: sleep for that many seconds and retry once.\n - Else if `X-RateLimit-Reset` exists: calculate time until reset; if <= 30 seconds, sleep and retry once; otherwise print a message advising the user to retry later (display reset time).\n - Else: do not retry; surface an actionable error with header details and a troubleshooting hint.\n\n3. Improve user-facing message and troubleshooting panel to include the headers and a short guidance text such as:\n - \"Tip: If you're on a shared CI or corporate environment, you may be rate-limited. Consider using a GitHub token via `--github-token` or the `GH_TOKEN`/`GITHUB_TOKEN` environment variable to increase rate limits.\"\n\n4. Optionally add a `--retry-on-rate-limit` flag to `specify init` (default: false) to allow users to opt-in to the automatic short retry behavior. The flag could be useful for automation contexts where waiting a few seconds is acceptable.\n\nSuggested patch outline\n- In `src/specify_cli/__init__.py` inside `download_template_from_github`:\n - After receiving the HTTP response, capture `headers = response.headers`.\n - On non-200, create a helpful `detail` string composed of the status and any present headers listed above.\n - If status is 429 or `X-RateLimit-Remaining == '0'`, follow the retry decision tree described above.\n - Use `rich.Panel` to display headers and guidance text when raising errors.\n\nTesting notes\n- Unit test: mock github API responses for the following cases and assert behavior/printed output:\n - 200 OK (no change)\n - 403 or 429 with `X-RateLimit-Remaining: 0` and `X-RateLimit-Reset` in near future (simulate retry path)\n - 403 or 429 with `Retry-After` header (simulate retry path)\n - 403 or 429 with no rate-limit headers (assert no retry and helpful error)\n- Integration test: run `download_template_from_github` against a local HTTP server that returns rate-limit headers to validate user-visible messages.\n\nYou can use this for additional documentation:\n- Keep retries conservative _(single short retry)_ to avoid long blocking behavior or masking larger rate-limit issues.\n- Prefer explicit guidance to using a GitHub token rather than silently retrying indefinitely.\n\nPotential bug with the create-new-feature.ps1 script that ignores existing feature branches when determining next feature number\n## Description\n\nThe PowerShell script `.specify/scripts/powershell/create-new-feature.ps1` only checks the `specs/` directory on the current branch to determine the next feature number, but does not check existing branch names. This causes numbering conflicts when working with multiple feature branches that haven't been merged to main.\n\n## Expected Behavior\n\nWhen running the script from `main`, it should:\n1. Check the `specs/` directory for existing spec folders with pattern `\\d{3}-*`\n2. **Also check `git branch` output for existing branches with pattern `\\d{3}-*`**\n3. Use the highest number found from either source\n4. Increment by 1 to determine the next feature number\n\n## Current Behavior\n\nThe script only checks step 1 (specs directory on current branch). If feature branches exist but haven't been merged to main, the script will reuse feature numbers, creating conflicts.\n\n## Reproduction Steps\n\n1. Initialize a new spec-kit project\n2. From `main` branch, run the script to create feature 001:\n powershell\n .\.specify\scripts\powershell\create-new-feature.ps1 -ShortName "first-feature"\n \n - Creates branch `001-first-feature`\n - Creates `specs/001-first-feature/` directory\n3. Push branch `001-first-feature` to remote (do NOT merge to main)\n4. Checkout `main` again\n5. Run the script to create feature 002:\n powershell\n .\.specify\scripts\powershell\create-new-feature.ps1 -ShortName "second-feature"\n \n\n**Expected**: Creates branch `002-second-feature` \n**Actual**: Creates branch `001-second-feature` (reuses 001)\n\n## Root Cause\n\nLooking at lines 82-92 of `create-new-feature.ps1`:\n\npowershell\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $.Name -match '^\d{3}' } |\n ForEach-Object {\n if ($.Name -match '^(\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n\nThe script only checks directories in `$specsDir`, not branch names via `git branch`.\n\n## Suggested Fix\n\nAdd branch checking logic before determining feature number:\n\npowershell\n# Get highest number from specs directory\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $.Name -match '^\d{3}' } |\n ForEach-Object {\n if ($.Name -match '^(\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Get highest number from branch names\n$existingBranches = git branch -a | \n ForEach-Object { $.Trim() -replace '^\*?\s+', '' -replace '^remotes/origin/', '' } |\n Where-Object { $ -match '^\d{3}-' } |\n ForEach-Object {\n if ($_ -match '^(\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Use the highest number from either source\n$highestExisting = [Math]::Max(\n $(if ($existingSpecs) { $existingSpecs } else { 0 }),\n $(if ($existingBranches) { $existingBranches } else { 0 })\n)\n\n$featureNumber = $highestExisting + 1\n\n\n## Workaround\n\nUntil fixed, merge spec directories to `main` after creating each feature branch, so the next run can see the previous feature number in the specs directory.\n\n## Environment\n\n- **OS**: Windows 11\n- **PowerShell Version**: 7.5.4\n- **spec-kit**: v0.0.20", "hints_text": "I like the idea of adding concrete error messages about rate limits, but don't want to bake in too much logic for retries - that's not the purpose of the CLI, and if all goes south anyway might as well just download the templates from the repo directly and extract them in the folder.\nThat sounds good to me and thanks for linking it to #986 - appreciate that! \n## \u2705 Fix Verified and Tested\n\nI can confirm the proposed fix works correctly! Here are the test results:\n\n### Test Setup\n\n1. Applied the suggested fix to `create-new-feature.ps1` (checking both specs/ directory AND git branches)\n2. Committed the fix to a `fix/branch-numbering-detection` branch\n3. Merged the fix to `main` branch\n4. Ran sequential feature creation tests\n\n### Test Results\n\n**Test 1 - Create First Feature:**\npowershell\n# From main branch\n/speckit.specify -ShortName "first-feature" Create a test feature to verify branch numbering\n\n- \u2705 Created branch: `001-first-feature`\n- \u2705 Committed and pushed to remote\n- \u2705 Returned to main branch\n\n**Test 2 - Create Second Feature (The Critical Test):**\npowershell\n# From main branch (001-first-feature exists ONLY on remote, not merged to main)\n/speckit.specify -ShortName "second-feature" Create another test feature to verify incremental numbering\n\n- \u2705 Created branch: `002-second-feature` (NOT `001-second-feature`)\n- \u2705 Correctly detected the existing `001-first-feature` branch on remote\n- \u2705 Incremented to `002` as expected\n\n### Fix Confirmation\n\nThe fix successfully:\n- \u2705 Detects existing feature branches from remote repository\n- \u2705 Prevents duplicate branch numbers\n- \u2705 Works correctly even when feature branches haven't been merged to main\n- \u2705 Checks both specs/ directory AND branch names\n- \u2705 Uses the highest number from either source\n\n### Implementation Details\n\nThe fix adds branch detection logic that:\n\n1. Scans all branches (local and remote) using `git branch -a`\n2. Strips remote prefixes (`remotes/origin/`)\n3. Extracts numeric prefixes matching `^\\d{3}-` pattern\n4. Compares highest number from branches vs. specs/ directory\n5. Uses `[Math]::Max()` to determine the starting point\n6. Increments by 1\n\n### Code Added\n\npowershell\n# Get highest number from branch names\n$existingBranches = git branch -a | \n ForEach-Object { $.Trim() -replace '^\*?\s+', '' -replace '^remotes/origin/', '' } |\n Where-Object { $ -match '^\d{3}-' } |\n ForEach-Object {\n if ($_ -match '^(\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Use the highest number from either source\n$highestExisting = [Math]::Max(\n $(if ($existingSpecs) { $existingSpecs } else { 0 }),\n $(if ($existingBranches) { $existingBranches } else { 0 })\n)\n\n$featureNumber = $highestExisting + 1\n\n\nThis fix resolves the issue completely and enables the proper workflow of creating multiple feature branches in parallel without requiring merges to main for correct numbering.\n\nHI there, i think this won't completly fix the problem with the branch numbering when using coding agents because the speckit.specify command prompt template instructs the agent to call the script with the `Number` parameter which bypasses this solution.\nI suggest to update the git commands in https://github.com/github/spec-kit/blob/main/templates/commands/specify.md aswell.\n### Template (Source)\n b. Find the highest feature number across all sources for the short-name:\n - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`\n - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`\n - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>``\n\n### Template (fix)\n b. Find the highest feature number across all sources for the short-name:\n - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-$'`\n - Local branches: `git branch | grep -E '^[* ]*[0-9]+-$'`\n - Specs directories: Check for directories matching `specs/[0-9]+-`\n\nAm i correct?", "resolved_issues": [{"number": 970, "title": "Add graceful fallback and logging for GitHub API rate-limiting during template fetch", "body": "Problem\n- `specify init` fetches release data and downloads assets from the GitHub Releases API. If the API rate-limits (or returns an unexpected status), the current error output can be terse and does not expose helpful headers like `X-RateLimit-Remaining`, `X-RateLimit-Reset`, or the `Retry-After` header. This makes diagnosing transient network or rate-limit issues harder for users and maintainers.\n\nWhy this helps\n- Displaying the relevant GitHub rate-limit headers and providing a sensible fallback makes failures easier to understand and act on. A fallback can also attempt a short backoff/retry for transient rate-limits and print the time when the client can retry based on `X-RateLimit-Reset`.\n\nProposed change\n1. Add header-aware error reporting in `download_template_from_github` (or the HTTP helper used) so that when a non-200 response is received, the error panel includes:\n - `status_code` and brief reason (already present)\n - `X-RateLimit-Limit` (if present)\n - `X-RateLimit-Remaining` (if present)\n - `X-RateLimit-Reset` (if present)-convert epoch seconds to a human-readable timestamp in the user's local timezone\n - `Retry-After` (if present)\n\n2. If the response status indicates rate limiting (HTTP 429) or `X-RateLimit-Remaining` is `0`, implement a simple optional retry strategy:\n - If `Retry-After` exists: sleep for that many seconds and retry once.\n - Else if `X-RateLimit-Reset` exists: calculate time until reset; if <= 30 seconds, sleep and retry once; otherwise print a message advising the user to retry later (display reset time).\n - Else: do not retry; surface an actionable error with header details and a troubleshooting hint.\n\n3. Improve user-facing message and troubleshooting panel to include the headers and a short guidance text such as:\n - \"Tip: If you're on a shared CI or corporate environment, you may be rate-limited. Consider using a GitHub token via `--github-token` or the `GH_TOKEN`/`GITHUB_TOKEN` environment variable to increase rate limits.\"\n\n4. Optionally add a `--retry-on-rate-limit` flag to `specify init` (default: false) to allow users to opt-in to the automatic short retry behavior. The flag could be useful for automation contexts where waiting a few seconds is acceptable.\n\nSuggested patch outline\n- In `src/specify_cli/__init__.py` inside `download_template_from_github`:\n - After receiving the HTTP response, capture `headers = response.headers`.\n - On non-200, create a helpful `detail` string composed of the status and any present headers listed above.\n - If status is 429 or `X-RateLimit-Remaining == '0'`, follow the retry decision tree described above.\n - Use `rich.Panel` to display headers and guidance text when raising errors.\n\nTesting notes\n- Unit test: mock github API responses for the following cases and assert behavior/printed output:\n - 200 OK (no change)\n - 403 or 429 with `X-RateLimit-Remaining: 0` and `X-RateLimit-Reset` in near future (simulate retry path)\n - 403 or 429 with `Retry-After` header (simulate retry path)\n - 403 or 429 with no rate-limit headers (assert no retry and helpful error)\n- Integration test: run `download_template_from_github` against a local HTTP server that returns rate-limit headers to validate user-visible messages.\n\nYou can use this for additional documentation:\n- Keep retries conservative _(single short retry)_ to avoid long blocking behavior or masking larger rate-limit issues.\n- Prefer explicit guidance to using a GitHub token rather than silently retrying indefinitely."}, {"number": 975, "title": "Potential bug with the create-new-feature.ps1 script that ignores existing feature branches when determining next feature number", "body": "## Description\n\nThe PowerShell script `.specify/scripts/powershell/create-new-feature.ps1` only checks the `specs/` directory on the current branch to determine the next feature number, but does not check existing branch names. This causes numbering conflicts when working with multiple feature branches that haven't been merged to main.\n\n## Expected Behavior\n\nWhen running the script from `main`, it should:\n1. Check the `specs/` directory for existing spec folders with pattern `\\d{3}-*`\n2. **Also check `git branch` output for existing branches with pattern `\\d{3}-*`**\n3. Use the highest number found from either source\n4. Increment by 1 to determine the next feature number\n\n## Current Behavior\n\nThe script only checks step 1 (specs directory on current branch). If feature branches exist but haven't been merged to main, the script will reuse feature numbers, creating conflicts.\n\n## Reproduction Steps\n\n1. Initialize a new spec-kit project\n2. From `main` branch, run the script to create feature 001:\n powershell\n .\.specify\scripts\powershell\create-new-feature.ps1 -ShortName "first-feature"\n \n - Creates branch `001-first-feature`\n - Creates `specs/001-first-feature/` directory\n3. Push branch `001-first-feature` to remote (do NOT merge to main)\n4. Checkout `main` again\n5. Run the script to create feature 002:\n powershell\n .\.specify\scripts\powershell\create-new-feature.ps1 -ShortName "second-feature"\n \n\n**Expected**: Creates branch `002-second-feature` \n**Actual**: Creates branch `001-second-feature` (reuses 001)\n\n## Root Cause\n\nLooking at lines 82-92 of `create-new-feature.ps1`:\n\npowershell\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $.Name -match '^\d{3}' } |\n ForEach-Object {\n if ($.Name -match '^(\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n\nThe script only checks directories in `$specsDir`, not branch names via `git branch`.\n\n## Suggested Fix\n\nAdd branch checking logic before determining feature number:\n\npowershell\n# Get highest number from specs directory\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $.Name -match '^\d{3}' } |\n ForEach-Object {\n if ($.Name -match '^(\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Get highest number from branch names\n$existingBranches = git branch -a | \n ForEach-Object { $.Trim() -replace '^\*?\s+', '' -replace '^remotes/origin/', '' } |\n Where-Object { $ -match '^\d{3}-' } |\n ForEach-Object {\n if ($_ -match '^(\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Use the highest number from either source\n$highestExisting = [Math]::Max(\n $(if ($existingSpecs) { $existingSpecs } else { 0 }),\n $(if ($existingBranches) { $existingBranches } else { 0 })\n)\n\n$featureNumber = $highestExisting + 1\n\n\n## Workaround\n\nUntil fixed, merge spec directories to `main` after creating each feature branch, so the next run can see the previous feature number in the specs directory.\n\n## Environment\n\n- **OS**: Windows 11\n- **PowerShell Version**: 7.5.4\n- **spec-kit**: v0.0.20"}], "base_commit": "e6d6f3cdee99752baee578896797400a72430ec0", "commit_to_review": {"head_commit": "392f8b7dfaba5d1d912f268d2830307da584b20f", "head_commit_message": "Update templates/commands/taskstoissues.md\n\nCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>", "patch_to_review": "diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml\nindex fa20c809d..5b37ed0be 100644\n--- a/.github/workflows/lint.yml\n+++ b/.github/workflows/lint.yml\n@@ -1,4 +1,6 @@\n name: Lint\n+permissions:\n+ contents: read\n \n on:\n push:\ndiff --git a/.github/workflows/scripts/create-release-packages.ps1 b/.github/workflows/scripts/create-release-packages.ps1\nnew file mode 100644\nindex 000000000..f935dbe86\n--- /dev/null\n+++ b/.github/workflows/scripts/create-release-packages.ps1\n@@ -0,0 +1,416 @@\n+#!/usr/bin/env pwsh\n+#requires -Version 7.0\n+\n+<#\n+.SYNOPSIS\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+\n+.DESCRIPTION\n+ create-release-packages.ps1 (workflow-local)\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+ \n+.PARAMETER Version\n+ Version string with leading 'v' (e.g., v0.2.0)\n+\n+.PARAMETER Agents\n+ Comma or space separated subset of agents to build (default: all)\n+ Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q\n+\n+.PARAMETER Scripts\n+ Comma or space separated subset of script types to build (default: both)\n+ Valid scripts: sh, ps\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0 -Agents claude,copilot -Scripts sh\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0 -Agents claude -Scripts ps\n+#>\n+\n+param(\n+ [Parameter(Mandatory=$true, Position=0)]\n+ [string]$Version,\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Agents = \"\",\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Scripts = \"\"\n+)\n+\n+$ErrorActionPreference = \"Stop\"\n+\n+# Validate version format\n+if ($Version -notmatch '^v\\d+\\.\\d+\\.\\d+$') {\n+ Write-Error \"Version must look like v0.0.0\"\n+ exit 1\n+}\n+\n+Write-Host \"Building release packages for $Version\"\n+\n+# Create and use .genreleases directory for all build artifacts\n+$GenReleasesDir = \".genreleases\"\n+if (Test-Path $GenReleasesDir) {\n+ Remove-Item -Path $GenReleasesDir -Recurse -Force -ErrorAction SilentlyContinue\n+}\n+New-Item -ItemType Directory -Path $GenReleasesDir -Force | Out-Null\n+\n+function Rewrite-Paths {\n+ param([string]$Content)\n+ \n+ $Content = $Content -replace '(/?)\\bmemory/', '.specify/memory/'\n+ $Content = $Content -replace '(/?)\\bscripts/', '.specify/scripts/'\n+ $Content = $Content -replace '(/?)\\btemplates/', '.specify/templates/'\n+ return $Content\n+}\n+\n+function Generate-Commands {\n+ param(\n+ [string]$Agent,\n+ [string]$Extension,\n+ [string]$ArgFormat,\n+ [string]$OutputDir,\n+ [string]$ScriptVariant\n+ )\n+ \n+ New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null\n+ \n+ $templates = Get-ChildItem -Path \"templates/commands/*.md\" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($template in $templates) {\n+ $name = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)\n+ \n+ # Read file content and normalize line endings\n+ $fileContent = (Get-Content -Path $template.FullName -Raw) -replace \"`r`n\", \"`n\"\n+ \n+ # Extract description from YAML frontmatter\n+ $description = \"\"\n+ if ($fileContent -match '(?m)^description:\\s*(.+)$') {\n+ $description = $matches[1]\n+ }\n+ \n+ # Extract script command from YAML frontmatter\n+ $scriptCommand = \"\"\n+ if ($fileContent -match \"(?m)^\\s*${ScriptVariant}:\\s*(.+)$\") {\n+ $scriptCommand = $matches[1]\n+ }\n+ \n+ if ([string]::IsNullOrEmpty($scriptCommand)) {\n+ Write-Warning \"No script command found for $ScriptVariant in $($template.Name)\"\n+ $scriptCommand = \"(Missing script command for $ScriptVariant)\"\n+ }\n+ \n+ # Extract agent_script command from YAML frontmatter if present\n+ $agentScriptCommand = \"\"\n+ if ($fileContent -match \"(?ms)agent_scripts:.*?^\\s*${ScriptVariant}:\\s*(.+?)$\") {\n+ $agentScriptCommand = $matches[1].Trim()\n+ }\n+ \n+ # Replace {SCRIPT} placeholder with the script command\n+ $body = $fileContent -replace '\\{SCRIPT\\}', $scriptCommand\n+ \n+ # Replace {AGENT_SCRIPT} placeholder with the agent script command if found\n+ if (-not [string]::IsNullOrEmpty($agentScriptCommand)) {\n+ $body = $body -replace '\\{AGENT_SCRIPT\\}', $agentScriptCommand\n+ }\n+ \n+ # Remove the scripts: and agent_scripts: sections from frontmatter\n+ $lines = $body -split \"`n\"\n+ $outputLines = @()\n+ $inFrontmatter = $false\n+ $skipScripts = $false\n+ $dashCount = 0\n+ \n+ foreach ($line in $lines) {\n+ if ($line -match '^---$') {\n+ $outputLines += $line\n+ $dashCount++\n+ if ($dashCount -eq 1) {\n+ $inFrontmatter = $true\n+ } else {\n+ $inFrontmatter = $false\n+ }\n+ continue\n+ }\n+ \n+ if ($inFrontmatter) {\n+ if ($line -match '^(scripts|agent_scripts):$') {\n+ $skipScripts = $true\n+ continue\n+ }\n+ if ($line -match '^[a-zA-Z].*:' -and $skipScripts) {\n+ $skipScripts = $false\n+ }\n+ if ($skipScripts -and $line -match '^\\s+') {\n+ continue\n+ }\n+ }\n+ \n+ $outputLines += $line\n+ }\n+ \n+ $body = $outputLines -join \"`n\"\n+ \n+ # Apply other substitutions\n+ $body = $body -replace '\\{ARGS\\}', $ArgFormat\n+ $body = $body -replace '__AGENT__', $Agent\n+ $body = Rewrite-Paths -Content $body\n+ \n+ # Generate output file based on extension\n+ $outputFile = Join-Path $OutputDir \"speckit.$name.$Extension\"\n+ \n+ switch ($Extension) {\n+ 'toml' {\n+ $body = $body -replace '\\\\', '\\\\'\n+ $output = \"description = `\"$description`\"`n`nprompt = `\"`\"`\"`n$body`n`\"`\"`\"\"\n+ Set-Content -Path $outputFile -Value $output -NoNewline\n+ }\n+ 'md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ 'agent.md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ }\n+ }\n+}\n+\n+function Generate-CopilotPrompts {\n+ param(\n+ [string]$AgentsDir,\n+ [string]$PromptsDir\n+ )\n+ \n+ New-Item -ItemType Directory -Path $PromptsDir -Force | Out-Null\n+ \n+ $agentFiles = Get-ChildItem -Path \"$AgentsDir/speckit.*.agent.md\" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($agentFile in $agentFiles) {\n+ $basename = $agentFile.Name -replace '\\.agent\\.md$', ''\n+ $promptFile = Join-Path $PromptsDir \"$basename.prompt.md\"\n+ \n+ $content = @\"\n+---\n+agent: $basename\n+---\n+\"@\n+ Set-Content -Path $promptFile -Value $content\n+ }\n+}\n+\n+function Build-Variant {\n+ param(\n+ [string]$Agent,\n+ [string]$Script\n+ )\n+ \n+ $baseDir = Join-Path $GenReleasesDir \"sdd-${Agent}-package-${Script}\"\n+ Write-Host \"Building $Agent ($Script) package...\"\n+ New-Item -ItemType Directory -Path $baseDir -Force | Out-Null\n+ \n+ # Copy base structure but filter scripts by variant\n+ $specDir = Join-Path $baseDir \".specify\"\n+ New-Item -ItemType Directory -Path $specDir -Force | Out-Null\n+ \n+ # Copy memory directory\n+ if (Test-Path \"memory\") {\n+ Copy-Item -Path \"memory\" -Destination $specDir -Recurse -Force\n+ Write-Host \"Copied memory -> .specify\"\n+ }\n+ \n+ # Only copy the relevant script variant directory\n+ if (Test-Path \"scripts\") {\n+ $scriptsDestDir = Join-Path $specDir \"scripts\"\n+ New-Item -ItemType Directory -Path $scriptsDestDir -Force | Out-Null\n+ \n+ switch ($Script) {\n+ 'sh' {\n+ if (Test-Path \"scripts/bash\") {\n+ Copy-Item -Path \"scripts/bash\" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host \"Copied scripts/bash -> .specify/scripts\"\n+ }\n+ }\n+ 'ps' {\n+ if (Test-Path \"scripts/powershell\") {\n+ Copy-Item -Path \"scripts/powershell\" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host \"Copied scripts/powershell -> .specify/scripts\"\n+ }\n+ }\n+ }\n+ \n+ # Copy any script files that aren't in variant-specific directories\n+ Get-ChildItem -Path \"scripts\" -File -ErrorAction SilentlyContinue | ForEach-Object {\n+ Copy-Item -Path $_.FullName -Destination $scriptsDestDir -Force\n+ }\n+ }\n+ \n+ # Copy templates (excluding commands directory and vscode-settings.json)\n+ if (Test-Path \"templates\") {\n+ $templatesDestDir = Join-Path $specDir \"templates\"\n+ New-Item -ItemType Directory -Path $templatesDestDir -Force | Out-Null\n+ \n+ Get-ChildItem -Path \"templates\" -Recurse -File | Where-Object {\n+ $_.FullName -notmatch 'templates[/\\\\]commands[/\\\\]' -and $_.Name -ne 'vscode-settings.json'\n+ } | ForEach-Object {\n+ $relativePath = $_.FullName.Substring((Resolve-Path \"templates\").Path.Length + 1)\n+ $destFile = Join-Path $templatesDestDir $relativePath\n+ $destFileDir = Split-Path $destFile -Parent\n+ New-Item -ItemType Directory -Path $destFileDir -Force | Out-Null\n+ Copy-Item -Path $_.FullName -Destination $destFile -Force\n+ }\n+ Write-Host \"Copied templates -> .specify/templates\"\n+ }\n+ \n+ # Generate agent-specific command files\n+ switch ($Agent) {\n+ 'claude' {\n+ $cmdDir = Join-Path $baseDir \".claude/commands\"\n+ Generate-Commands -Agent 'claude' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'gemini' {\n+ $cmdDir = Join-Path $baseDir \".gemini/commands\"\n+ Generate-Commands -Agent 'gemini' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path \"agent_templates/gemini/GEMINI.md\") {\n+ Copy-Item -Path \"agent_templates/gemini/GEMINI.md\" -Destination (Join-Path $baseDir \"GEMINI.md\")\n+ }\n+ }\n+ 'copilot' {\n+ $agentsDir = Join-Path $baseDir \".github/agents\"\n+ Generate-Commands -Agent 'copilot' -Extension 'agent.md' -ArgFormat '$ARGUMENTS' -OutputDir $agentsDir -ScriptVariant $Script\n+ \n+ # Generate companion prompt files\n+ $promptsDir = Join-Path $baseDir \".github/prompts\"\n+ Generate-CopilotPrompts -AgentsDir $agentsDir -PromptsDir $promptsDir\n+ \n+ # Create VS Code workspace settings\n+ $vscodeDir = Join-Path $baseDir \".vscode\"\n+ New-Item -ItemType Directory -Path $vscodeDir -Force | Out-Null\n+ if (Test-Path \"templates/vscode-settings.json\") {\n+ Copy-Item -Path \"templates/vscode-settings.json\" -Destination (Join-Path $vscodeDir \"settings.json\")\n+ }\n+ }\n+ 'cursor-agent' {\n+ $cmdDir = Join-Path $baseDir \".cursor/commands\"\n+ Generate-Commands -Agent 'cursor-agent' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'qwen' {\n+ $cmdDir = Join-Path $baseDir \".qwen/commands\"\n+ Generate-Commands -Agent 'qwen' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path \"agent_templates/qwen/QWEN.md\") {\n+ Copy-Item -Path \"agent_templates/qwen/QWEN.md\" -Destination (Join-Path $baseDir \"QWEN.md\")\n+ }\n+ }\n+ 'opencode' {\n+ $cmdDir = Join-Path $baseDir \".opencode/command\"\n+ Generate-Commands -Agent 'opencode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'windsurf' {\n+ $cmdDir = Join-Path $baseDir \".windsurf/workflows\"\n+ Generate-Commands -Agent 'windsurf' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codex' {\n+ $cmdDir = Join-Path $baseDir \".codex/prompts\"\n+ Generate-Commands -Agent 'codex' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'kilocode' {\n+ $cmdDir = Join-Path $baseDir \".kilocode/workflows\"\n+ Generate-Commands -Agent 'kilocode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'auggie' {\n+ $cmdDir = Join-Path $baseDir \".augment/commands\"\n+ Generate-Commands -Agent 'auggie' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'roo' {\n+ $cmdDir = Join-Path $baseDir \".roo/commands\"\n+ Generate-Commands -Agent 'roo' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codebuddy' {\n+ $cmdDir = Join-Path $baseDir \".codebuddy/commands\"\n+ Generate-Commands -Agent 'codebuddy' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'amp' {\n+ $cmdDir = Join-Path $baseDir \".agents/commands\"\n+ Generate-Commands -Agent 'amp' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'q' {\n+ $cmdDir = Join-Path $baseDir \".amazonq/prompts\"\n+ Generate-Commands -Agent 'q' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ }\n+ \n+ # Create zip archive\n+ $zipFile = Join-Path $GenReleasesDir \"spec-kit-template-${Agent}-${Script}-${Version}.zip\"\n+ Compress-Archive -Path \"$baseDir/*\" -DestinationPath $zipFile -Force\n+ Write-Host \"Created $zipFile\"\n+}\n+\n+# Define all agents and scripts\n+$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q')\n+$AllScripts = @('sh', 'ps')\n+\n+function Normalize-List {\n+ param([string]$Input)\n+ \n+ if ([string]::IsNullOrEmpty($Input)) {\n+ return @()\n+ }\n+ \n+ # Split by comma or space and remove duplicates while preserving order\n+ $items = $Input -split '[,\\s]+' | Where-Object { $_ } | Select-Object -Unique\n+ return $items\n+}\n+\n+function Validate-Subset {\n+ param(\n+ [string]$Type,\n+ [string[]]$Allowed,\n+ [string[]]$Items\n+ )\n+ \n+ $ok = $true\n+ foreach ($item in $Items) {\n+ if ($item -notin $Allowed) {\n+ Write-Error \"Unknown $Type '$item' (allowed: $($Allowed -join ', '))\"\n+ $ok = $false\n+ }\n+ }\n+ return $ok\n+}\n+\n+# Determine agent list\n+if (-not [string]::IsNullOrEmpty($Agents)) {\n+ $AgentList = Normalize-List -Input $Agents\n+ if (-not (Validate-Subset -Type 'agent' -Allowed $AllAgents -Items $AgentList)) {\n+ exit 1\n+ }\n+} else {\n+ $AgentList = $AllAgents\n+}\n+\n+# Determine script list\n+if (-not [string]::IsNullOrEmpty($Scripts)) {\n+ $ScriptList = Normalize-List -Input $Scripts\n+ if (-not (Validate-Subset -Type 'script' -Allowed $AllScripts -Items $ScriptList)) {\n+ exit 1\n+ }\n+} else {\n+ $ScriptList = $AllScripts\n+}\n+\n+Write-Host \"Agents: $($AgentList -join ', ')\"\n+Write-Host \"Scripts: $($ScriptList -join ', ')\"\n+\n+# Build all variants\n+foreach ($agent in $AgentList) {\n+ foreach ($script in $ScriptList) {\n+ Build-Variant -Agent $agent -Script $script\n+ }\n+}\n+\n+Write-Host \"`nArchives in ${GenReleasesDir}:\"\n+Get-ChildItem -Path $GenReleasesDir -Filter \"spec-kit-template-*-${Version}.zip\" | ForEach-Object {\n+ Write-Host \" $($_.Name)\"\n+}\ndiff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh\nindex f9d3b1ae1..1b2e53265 100644\n--- a/.github/workflows/scripts/create-release-packages.sh\n+++ b/.github/workflows/scripts/create-release-packages.sh\n@@ -95,12 +95,32 @@ generate_commands() {\n { echo \"description = \\\"$description\\\"\"; echo; echo \"prompt = \\\"\\\"\\\"\"; echo \"$body\"; echo \"\\\"\\\"\\\"\"; } > \"$output_dir/speckit.$name.$ext\" ;;\n md)\n echo \"$body\" > \"$output_dir/speckit.$name.$ext\" ;;\n- prompt.md)\n+ agent.md)\n echo \"$body\" > \"$output_dir/speckit.$name.$ext\" ;;\n esac\n done\n }\n \n+generate_copilot_prompts() {\n+ local agents_dir=$1 prompts_dir=$2\n+ mkdir -p \"$prompts_dir\"\n+ \n+ # Generate a .prompt.md file for each .agent.md file\n+ for agent_file in \"$agents_dir\"/speckit.*.agent.md; do\n+ [[ -f \"$agent_file\" ]] || continue\n+ \n+ local basename=$(basename \"$agent_file\" .agent.md)\n+ local prompt_file=\"$prompts_dir/${basename}.prompt.md\"\n+ \n+ # Create prompt file with agent frontmatter\n+ cat > \"$prompt_file\" <<EOF\n+---\n+agent: ${basename}\n+---\n+EOF\n+ done\n+}\n+\n build_variant() {\n local agent=$1 script=$2\n local base_dir=\"$GENRELEASES_DIR/sdd-${agent}-package-${script}\"\n@@ -146,8 +166,10 @@ build_variant() {\n generate_commands gemini toml \"{{args}}\" \"$base_dir/.gemini/commands\" \"$script\"\n [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md \"$base_dir/GEMINI.md\" ;;\n copilot)\n- mkdir -p \"$base_dir/.github/prompts\"\n- generate_commands copilot prompt.md \"\\$ARGUMENTS\" \"$base_dir/.github/prompts\" \"$script\"\n+ mkdir -p \"$base_dir/.github/agents\"\n+ generate_commands copilot agent.md \"\\$ARGUMENTS\" \"$base_dir/.github/agents\" \"$script\"\n+ # Generate companion prompt files\n+ generate_copilot_prompts \"$base_dir/.github/agents\" \"$base_dir/.github/prompts\"\n # Create VS Code workspace settings\n mkdir -p \"$base_dir/.vscode\"\n [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json \"$base_dir/.vscode/settings.json\"\ndiff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc\nindex a96fd3e6d..d6db02777 100644\n--- a/.markdownlint-cli2.jsonc\n+++ b/.markdownlint-cli2.jsonc\n@@ -20,5 +20,8 @@\n \"MD050\": {\n \"style\": \"asterisk\"\n }\n- }\n+ },\n+ \"ignores\": [\n+ \".genreleases/\"\n+ ]\n }\n\\ No newline at end of file\ndiff --git a/AGENTS.md b/AGENTS.md\nindex d34efb673..f7d956bd7 100644\n--- a/AGENTS.md\n+++ b/AGENTS.md\n@@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a\n |-------|-----------|---------|----------|-------------|\n | **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code CLI |\n | **Gemini CLI** | `.gemini/commands/` | TOML | `gemini` | Google's Gemini CLI |\n-| **GitHub Copilot** | `.github/prompts/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n+| **GitHub Copilot** | `.github/agents/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n | **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI |\n | **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI |\n | **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI |\n@@ -325,9 +325,22 @@ Work within integrated development environments:\n \n Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp\n \n+**Standard format:**\n+\n+markdown\n+---\n+description: "Command description"\n+---\n+\n+Command content with {SCRIPT} and $ARGUMENTS placeholders.\n+\n+\n+**GitHub Copilot Chat Mode format:**\n+\n markdown\n ---\n description: "Command description"\n+mode: speckit.command-name\n ---\n \n Command content with {SCRIPT} and $ARGUMENTS placeholders.\n@@ -349,7 +362,7 @@ Command content with {SCRIPT} and {{args}} placeholders.\n \n - CLI agents: Usually .<agent-name>/commands/\n - IDE agents: Follow IDE-specific patterns:\n- - Copilot: .github/prompts/\n+ - Copilot: .github/agents/\n - Cursor: .cursor/commands/\n - Windsurf: .windsurf/workflows/\n \ndiff --git a/CHANGELOG.md b/CHANGELOG.md\nindex ea6729145..7e2ac3697 100644\n--- a/CHANGELOG.md\n+++ b/CHANGELOG.md\n@@ -7,6 +7,22 @@ All notable changes to the Specify CLI and templates are documented here.\n The format is based on Keep a Changelog,\n and this project adheres to Semantic Versioning.\n \n+## [0.0.22] - 2025-11-07\n+\n+- Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.\n+- Move to use AGENTS.md for Copilot workloads, since it's already supported out-of-the-box.\n+- Adds support for the version command. (#486)\n+- Fixes potential bug with the create-new-feature.ps1 script that ignores existing feature branches when determining next feature number (#975)\n+- Add graceful fallback and logging for GitHub API rate-limiting during template fetch (#970)\n+\n+## [0.0.21] - 2025-10-21\n+\n+- Fixes #975 (thank you @fgalarraga).\n+- Adds support for Amp CLI.\n+- Adds support for VS Code hand-offs and moves prompts to be full-fledged chat modes.\n+- Adds support for version command (addresses #811 and #486, thank you @mcasalaina and @dentity007).\n+- Adds support for rendering the rate limit errors from the CLI when encountered (#970, thank you @psmman).\n+\n ## [0.0.20] - 2025-10-14\n \n ### Added\ndiff --git a/CONTRIBUTING.md b/CONTRIBUTING.md\nindex e5897b383..c413dd018 100644\n--- a/CONTRIBUTING.md\n+++ b/CONTRIBUTING.md\n@@ -70,6 +70,7 @@ To test your templates, commands, and other changes locally, follow these steps:\n 1. Create release packages\n \n Run the following command to generate the local packages:\n+\n \n ./.github/workflows/scripts/create-release-packages.sh v1.0.0\n \ndiff --git a/pyproject.toml b/pyproject.toml\nindex 567d48cd4..fb972adc7 100644\n--- a/pyproject.toml\n+++ b/pyproject.toml\n@@ -1,6 +1,6 @@\n [project]\n name = "specify-cli"\n-version = "0.0.20"\n+version = "0.0.22"\n description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."\n requires-python = ">=3.11"\n dependencies = [\ndiff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh\nindex 86d9ecf83..ed244282b 100644\n--- a/scripts/bash/create-new-feature.sh\n+++ b/scripts/bash/create-new-feature.sh\n@@ -133,6 +133,48 @@ cd "$REPO_ROOT"\n SPECS_DIR="$REPO_ROOT/specs"\n mkdir -p "$SPECS_DIR"\n \n+# Get highest number from specs directory\n+HIGHEST_FROM_SPECS=0\n+if [ -d "$SPECS_DIR" ]; then\n+ for dir in "$SPECS_DIR"/; do\n+ [ -d "$dir" ] || continue\n+ dirname=$(basename "$dir")\n+ number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")\n+ number=$((10#$number))\n+ if [ "$number" -gt "$HIGHEST_FROM_SPECS" ]; then HIGHEST_FROM_SPECS=$number; fi\n+ done\n+fi\n+\n+# Get highest number from branch names (both local and remote)\n+HIGHEST_FROM_BRANCHES=0\n+if [ "$HAS_GIT" = true ]; then\n+ # Get all branches (local and remote)\n+ branches=$(git branch -a 2>/dev/null || echo "")\n+ \n+ if [ -n "$branches" ]; then\n+ while IFS= read -r branch; do\n+ # Clean branch name: remove leading markers and remote prefixes\n+ clean_branch=$(echo "$branch" | sed 's/^[ ]//; s|^remotes/[^/]/||')\n+ \n+ # Extract feature number if branch matches pattern ###-\n+ if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then\n+ number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")\n+ number=$((10#$number))\n+ if [ "$number" -gt "$HIGHEST_FROM_BRANCHES" ]; then HIGHEST_FROM_BRANCHES=$number; fi\n+ fi\n+ done <<< "$branches"\n+ fi\n+fi\n+\n+# Use the highest number from either source\n+HIGHEST=$HIGHEST_FROM_SPECS\n+if [ "$HIGHEST_FROM_BRANCHES" -gt "$HIGHEST" ]; then\n+ HIGHEST=$HIGHEST_FROM_BRANCHES\n+fi\n+\n+NEXT=$((HIGHEST + 1))\n+FEATURE_NUM=$(printf "%03d" "$NEXT")\n+\n # Function to generate branch name with stop word filtering and length filtering\n generate_branch_name() {\n local description="$1"\ndiff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh\nindex 2a44c68a1..fcb525ac0 100644\n--- a/scripts/bash/update-agent-context.sh\n+++ b/scripts/bash/update-agent-context.sh\n@@ -61,7 +61,8 @@ AGENT_TYPE="${1:-}"\n # Agent-specific file paths \n CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"\n GEMINI_FILE="$REPO_ROOT/GEMINI.md"\n-COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"\n+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"\n+COPILOT_AGENTS_FILE="$REPO_ROOT/AGENTS.md"\n CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"\n QWEN_FILE="$REPO_ROOT/QWEN.md"\n AGENTS_FILE="$REPO_ROOT/AGENTS.md"\n@@ -587,6 +588,7 @@ update_specific_agent() {\n ;;\n copilot)\n update_agent_file "$COPILOT_FILE" "GitHub Copilot"\n+ update_agent_file "$COPILOT_AGENTS_FILE" "GitHub Copilot (AGENTS.md)"\n ;;\n cursor-agent)\n update_agent_file "$CURSOR_FILE" "Cursor IDE"\n@@ -648,6 +650,12 @@ update_all_existing_agents() {\n found_agent=true\n fi\n \n+ # Also update AGENTS.md for Copilot if the Copilot directory exists\n+ if [[ -d "$REPO_ROOT/.github/agents" ]]; then\n+ update_agent_file "$COPILOT_AGENTS_FILE" "GitHub Copilot (AGENTS.md)"\n+ found_agent=true\n+ fi\n+ \n if [[ -f "$CURSOR_FILE" ]]; then\n update_agent_file "$CURSOR_FILE" "Cursor IDE"\n found_agent=true\ndiff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1\nindex 4daa6d2c0..db92c3f77 100644\n--- a/scripts/powershell/create-new-feature.ps1\n+++ b/scripts/powershell/create-new-feature.ps1\n@@ -150,6 +150,46 @@ Set-Location $repoRoot\n $specsDir = Join-Path $repoRoot 'specs'\n New-Item -ItemType Directory -Path $specsDir -Force | Out-Null\n \n+# Get highest number from specs directory\n+$highestFromSpecs = 0\n+if (Test-Path $specsDir) {\n+ Get-ChildItem -Path $specsDir -Directory | ForEach-Object {\n+ if ($_.Name -match '^(\d{3})') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromSpecs) { $highestFromSpecs = $num }\n+ }\n+ }\n+}\n+\n+# Get highest number from branch names (both local and remote)\n+$highestFromBranches = 0\n+try {\n+ $branches = git branch -a 2>$null\n+ if ($LASTEXITCODE -eq 0) {\n+ foreach ($branch in $branches) {\n+ # Clean branch name: remove leading markers and remote prefixes\n+ # The following regex removes:\n+ # - Git's current branch marker ('') and leading whitespace (e.g., '* main')\n+ # - Remote prefixes (e.g., 'remotes/origin/')\n+ $cleanBranch = $branch.Trim() -replace '^\?\s+', '' -replace '^remotes/[^/]+/', ''\n+ \n+ # Extract feature number if branch matches pattern ###-\n+ if ($cleanBranch -match '^(\d{3})-') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromBranches) { $highestFromBranches = $num }\n+ }\n+ }\n+ }\n+} catch {\n+ # If git command fails, just continue with specs-only check\n+ Write-Verbose "Could not check Git branches: $_"\n+}\n+\n+# Use the highest number from either source\n+$highest = [Math]::Max($highestFromSpecs, $highestFromBranches)\n+$next = $highest + 1\n+$featureNum = ('{0:000}' -f $next)\n+\n # Function to generate branch name with stop word filtering and length filtering\n function Get-BranchName {\n param([string]$Description)\ndiff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1\nindex db6e9f2d7..d0ed582fa 100644\n--- a/scripts/powershell/setup-plan.ps1\n+++ b/scripts/powershell/setup-plan.ps1\n@@ -59,4 +59,3 @@ if ($Json) {\n Write-Output "BRANCH: $($paths.CURRENT_BRANCH)"\n Write-Output "HAS_GIT: $($paths.HAS_GIT)"\n }\n-\ndiff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1\nindex 695e28b8d..a439cc435 100644\n--- a/scripts/powershell/update-agent-context.ps1\n+++ b/scripts/powershell/update-agent-context.ps1\n@@ -46,7 +46,8 @@ $NEW_PLAN = $IMPL_PLAN\n # Agent file paths\n $CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md'\n $GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md'\n-$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md'\n+$COPILOT_FILE = Join-Path $REPO_ROOT '.github/agents/copilot-instructions.md'\n+$COPILOT_AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md'\n $CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc'\n $QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md'\n $AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md'\n@@ -370,7 +371,10 @@ function Update-SpecificAgent {\n switch ($Type) {\n 'claude' { Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code' }\n 'gemini' { Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI' }\n- 'copilot' { Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot' }\n+ 'copilot' { \n+ Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot'\n+ Update-AgentFile -TargetFile $COPILOT_AGENTS_FILE -AgentName 'GitHub Copilot (AGENTS.md)'\n+ }\n 'cursor-agent' { Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE' }\n 'qwen' { Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code' }\n 'opencode' { Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'opencode' }\n@@ -392,6 +396,8 @@ function Update-AllExistingAgents {\n if (Test-Path $CLAUDE_FILE) { if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false }; $found = $true }\n if (Test-Path $GEMINI_FILE) { if (-not (Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI')) { $ok = $false }; $found = $true }\n if (Test-Path $COPILOT_FILE) { if (-not (Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot')) { $ok = $false }; $found = $true }\n+ # Also update AGENTS.md for Copilot if the Copilot directory exists\n+ if (Test-Path (Join-Path $REPO_ROOT '.github/agents')) { if (-not (Update-AgentFile -TargetFile $COPILOT_AGENTS_FILE -AgentName 'GitHub Copilot (AGENTS.md)')) { $ok = $false }; $found = $true }\n if (Test-Path $CURSOR_FILE) { if (-not (Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE')) { $ok = $false }; $found = $true }\n if (Test-Path $QWEN_FILE) { if (-not (Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code')) { $ok = $false }; $found = $true }\n if (Test-Path $AGENTS_FILE) { if (-not (Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex/opencode')) { $ok = $false }; $found = $true }\ndiff --git a/src/specify_cli/init.py b/src/specify_cli/init.py\nindex a33a1c61a..701b3bdca 100644\n--- a/src/specify_cli/init.py\n+++ b/src/specify_cli/init.py\n@@ -51,6 +51,7 @@\n import readchar\n import ssl\n import truststore\n+from datetime import datetime, timezone\n \n ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)\n client = httpx.Client(verify=ssl_context)\n@@ -64,6 +65,63 @@ def _github_auth_headers(cli_token: str | None = None) -> dict:\n token = _github_token(cli_token)\n return {"Authorization": f"Bearer {token}"} if token else {}\n \n+def _parse_rate_limit_headers(headers: httpx.Headers) -> dict:\n+ """Extract and parse GitHub rate-limit headers."""\n+ info = {}\n+ \n+ # Standard GitHub rate-limit headers\n+ if "X-RateLimit-Limit" in headers:\n+ info["limit"] = headers.get("X-RateLimit-Limit")\n+ if "X-RateLimit-Remaining" in headers:\n+ info["remaining"] = headers.get("X-RateLimit-Remaining")\n+ if "X-RateLimit-Reset" in headers:\n+ reset_epoch = int(headers.get("X-RateLimit-Reset", "0"))\n+ if reset_epoch:\n+ reset_time = datetime.fromtimestamp(reset_epoch, tz=timezone.utc)\n+ info["reset_epoch"] = reset_epoch\n+ info["reset_time"] = reset_time\n+ info["reset_local"] = reset_time.astimezone()\n+ \n+ # Retry-After header (seconds or HTTP-date)\n+ if "Retry-After" in headers:\n+ retry_after = headers.get("Retry-After")\n+ try:\n+ info["retry_after_seconds"] = int(retry_after)\n+ except ValueError:\n+ # HTTP-date format - not implemented, just store as string\n+ info["retry_after"] = retry_after\n+ \n+ return info\n+\n+def format_rate_limit_error(status_code: int, headers: httpx.Headers, url: str) -> str:\n+ """Format a user-friendly error message with rate-limit information."""\n+ rate_info = parse_rate_limit_headers(headers)\n+ \n+ lines = [f"GitHub API returned status {status_code} for {url}"]\n+ lines.append("")\n+ \n+ if rate_info:\n+ lines.append("[bold]Rate Limit Information:[/bold]")\n+ if "limit" in rate_info:\n+ lines.append(f" \u2022 Rate Limit: {rate_info['limit']} requests/hour")\n+ if "remaining" in rate_info:\n+ lines.append(f" \u2022 Remaining: {rate_info['remaining']}")\n+ if "reset_local" in rate_info:\n+ reset_str = rate_info["reset_local"].strftime("%Y-%m-%d %H:%M:%S %Z")\n+ lines.append(f" \u2022 Resets at: {reset_str}")\n+ if "retry_after_seconds" in rate_info:\n+ lines.append(f" \u2022 Retry after: {rate_info['retry_after_seconds']} seconds")\n+ lines.append("")\n+ \n+ # Add troubleshooting guidance\n+ lines.append("[bold]Troubleshooting Tips:[/bold]")\n+ lines.append(" \u2022 If you're on a shared CI or corporate environment, you may be rate-limited.")\n+ lines.append(" \u2022 Consider using a GitHub token via --github-token or the GH_TOKEN/GITHUB_TOKEN")\n+ lines.append(" environment variable to increase rate limits.")\n+ lines.append(" \u2022 Authenticated requests have a limit of 5,000/hour vs 60/hour for unauthenticated.")\n+ \n+ return "\n".join(lines)\n+\n # Agent configuration with name, folder, install URL, and CLI tool requirement\n AGENT_CONFIG = {\n "copilot": {\n@@ -577,10 +635,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, , scri\n )\n status = response.status_code\n if status != 200:\n- msg = f"GitHub API returned {status} for {api_url}"\n+ # Format detailed error message with rate-limit info\n+ error_msg = _format_rate_limit_error(status, response.headers, api_url)\n if debug:\n- msg += f"\nResponse headers: {response.headers}\nBody (truncated 500): {response.text[:500]}"\n- raise RuntimeError(msg)\n+ error_msg += f"\n\n[dim]Response body (truncated 500):[/dim]\n{response.text[:500]}"\n+ raise RuntimeError(error_msg)\n try:\n release_data = response.json()\n except ValueError as je:\n@@ -627,8 +686,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, , scri\n headers=_github_auth_headers(github_token),\n ) as response:\n if response.status_code != 200:\n- body_sample = response.text[:400]\n- raise RuntimeError(f"Download failed with {response.status_code}\nHeaders: {response.headers}\nBody (truncated): {body_sample}")\n+ # Handle rate-limiting on download as well\n+ error_msg = _format_rate_limit_error(response.status_code, response.headers, download_url)\n+ if debug:\n+ error_msg += f"\n\n[dim]Response body (truncated 400):[/dim]\n{response.text[:400]}"\n+ raise RuntimeError(error_msg)\n total_size = int(response.headers.get('content-length', 0))\n with open(zip_path, 'wb') as f:\n if total_size == 0:\n@@ -1202,6 +1264,85 @@ def check():\n if not any(agent_results.values()):\n console.print("[dim]Tip: Install an AI assistant for the best experience[/dim]")\n \n+@app.command()\n+def version():\n+ """Display version and system information."""\n+ import platform\n+ import importlib.metadata\n+ \n+ show_banner()\n+ \n+ # Get CLI version from package metadata\n+ cli_version = "unknown"\n+ try:\n+ cli_version = importlib.metadata.version("specify-cli")\n+ except Exception:\n+ # Fallback: try reading from pyproject.toml if running from source\n+ try:\n+ import tomllib\n+ pyproject_path = Path(file).parent.parent.parent / "pyproject.toml"\n+ if pyproject_path.exists():\n+ with open(pyproject_path, "rb") as f:\n+ data = tomllib.load(f)\n+ cli_version = data.get("project", {}).get("version", "unknown")\n+ except Exception:\n+ pass\n+ \n+ # Fetch latest template release version\n+ repo_owner = "github"\n+ repo_name = "spec-kit"\n+ api_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest"\n+ \n+ template_version = "unknown"\n+ release_date = "unknown"\n+ \n+ try:\n+ response = client.get(\n+ api_url,\n+ timeout=10,\n+ follow_redirects=True,\n+ headers=github_auth_headers(),\n+ )\n+ if response.status_code == 200:\n+ release_data = response.json()\n+ template_version = release_data.get("tag_name", "unknown")\n+ # Remove 'v' prefix if present\n+ if template_version.startswith("v"):\n+ template_version = template_version[1:]\n+ release_date = release_data.get("published_at", "unknown")\n+ if release_date != "unknown":\n+ # Format the date nicely\n+ try:\n+ dt = datetime.fromisoformat(release_date.replace('Z', '+00:00'))\n+ release_date = dt.strftime("%Y-%m-%d")\n+ except Exception:\n+ pass\n+ except Exception:\n+ pass\n+\n+ info_table = Table(show_header=False, box=None, padding=(0, 2))\n+ info_table.add_column("Key", style="cyan", justify="right")\n+ info_table.add_column("Value", style="white")\n+\n+ info_table.add_row("CLI Version", cli_version)\n+ info_table.add_row("Template Version", template_version)\n+ info_table.add_row("Released", release_date)\n+ info_table.add_row("", "")\n+ info_table.add_row("Python", platform.python_version())\n+ info_table.add_row("Platform", platform.system())\n+ info_table.add_row("Architecture", platform.machine())\n+ info_table.add_row("OS Version", platform.version())\n+\n+ panel = Panel(\n+ info_table,\n+ title="[bold cyan]Specify CLI Information[/bold cyan]",\n+ border_style="cyan",\n+ padding=(1, 2)\n+ )\n+\n+ console.print(panel)\n+ console.print()\n+\n def main():\n app()\n \ndiff --git a/templates/commands/clarify.md b/templates/commands/clarify.md\nindex 9a62dfa74..4de842aa6 100644\n--- a/templates/commands/clarify.md\n+++ b/templates/commands/clarify.md\n@@ -1,5 +1,9 @@\n ---\n description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json --paths-only\n ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly\ndiff --git a/templates/commands/constitution.md b/templates/commands/constitution.md\nindex f557dd17c..cf81f08c2 100644\n--- a/templates/commands/constitution.md\n+++ b/templates/commands/constitution.md\n@@ -1,5 +1,9 @@\n ---\n-description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync\n+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.\n+handoffs: \n+ - label: Build Specification\n+ agent: speckit.specify\n+ prompt: Implement the feature specification based on the updated constitution. I want to build...\n ---\n \n ## User Input\ndiff --git a/templates/commands/implement.md b/templates/commands/implement.md\nindex 38601920d..fde3651e2 100644\n--- a/templates/commands/implement.md\n+++ b/templates/commands/implement.md\n@@ -135,4 +135,3 @@ You MUST consider the user input before proceeding (if not empty).\n - Report final status with summary of completed work\n \n Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running /speckit.tasks first to regenerate the task list.\n-\ndiff --git a/templates/commands/plan.md b/templates/commands/plan.md\nindex 7dfe63a2f..147da0afa 100644\n--- a/templates/commands/plan.md\n+++ b/templates/commands/plan.md\n@@ -1,5 +1,13 @@\n ---\n description: Execute the implementation planning workflow using the plan template to generate design artifacts.\n+handoffs: \n+ - label: Create Tasks\n+ agent: speckit.tasks\n+ prompt: Break the plan into tasks\n+ send: true\n+ - label: Create Checklist\n+ agent: speckit.checklist\n+ prompt: Create a checklist for the following domain...\n scripts:\n sh: scripts/bash/setup-plan.sh --json\n ps: scripts/powershell/setup-plan.ps1 -Json\ndiff --git a/templates/commands/specify.md b/templates/commands/specify.md\nindex 69258a8bf..3f0ddb78b 100644\n--- a/templates/commands/specify.md\n+++ b/templates/commands/specify.md\n@@ -1,5 +1,13 @@\n ---\n description: Create or update the feature specification from a natural language feature description.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n+ - label: Clarify Spec Requirements\n+ agent: speckit.clarify\n+ prompt: Clarify specification requirements\n+ send: true\n scripts:\n sh: scripts/bash/create-new-feature.sh --json "{ARGS}"\n ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"\ndiff --git a/templates/commands/tasks.md b/templates/commands/tasks.md\nindex 4663c1b67..86a766829 100644\n--- a/templates/commands/tasks.md\n+++ b/templates/commands/tasks.md\n@@ -1,5 +1,14 @@\n ---\n description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.\n+handoffs: \n+ - label: Analyze For Consistency\n+ agent: speckit.analyze\n+ prompt: Run a project analysis for consistency\n+ send: true\n+ - label: Implement Project\n+ agent: speckit.implement\n+ prompt: Start the implementation in phases\n+ send: true\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json\n ps: scripts/powershell/check-prerequisites.ps1 -Json\ndiff --git a/templates/commands/taskstoissues.md b/templates/commands/taskstoissues.md\nnew file mode 100644\nindex 000000000..e0f366372\n--- /dev/null\n+++ b/templates/commands/taskstoissues.md\n@@ -0,0 +1,31 @@\n+---\n+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.\n+tools: ['github/github-mcp-server/create_issue']\n+scripts:\n+ sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks\n+ ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks\n+---\n+\n+## User Input\n+\n+text\n+$ARGUMENTS\n+\n+\n+You MUST consider the user input before proceeding (if not empty).\n+\n+## Outline\n+\n+1. Run {SCRIPT} from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").\n+1. From the executed script, extract the path to tasks.\n+1. Get the Git remote by running:\n+\n+bash\n+git config --get remote.origin.url\n+\n+\n+ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL\n+\n+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.\n+\n+UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL\n"}, "reference_review_comments": [{"text": "@user1:\nThis new feature numbering logic duplicates the existing Get-NextBranchNumber function (lines 62-129). The new code at lines 153-191 calculates feature numbers from specs and branches generically, while Get-NextBranchNumber does the same but filtered by a specific branch suffix. This creates redundant logic that needs to be maintained in parallel. Consider refactoring Get-NextBranchNumber to support both use cases (with and without a suffix filter), or extracting the common logic into a shared helper function.\nsuggestion\nfunction Get-NextFeatureNumber {\n param(\n [string]$SpecsDir,\n [string]$BranchSuffix = $null\n )\n $highestFromSpecs = 0\n if (Test-Path $SpecsDir) {\n Get-ChildItem -Path $SpecsDir -Directory | ForEach-Object {\n if ($_.Name -match '^(\\d{3})') {\n $num = [int]$matches[1]\n if ($num -gt $highestFromSpecs) { $highestFromSpecs = $num }\n }\n }\n }\n $highestFromBranches = 0\n try {\n $branches = git branch -a 2>$null\n if ($LASTEXITCODE -eq 0) {\n foreach ($branch in $branches) {\n $cleanBranch = $branch.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/[^/]+/', ''\n # If a branch suffix is specified, filter branches\n if ($BranchSuffix -and -not ($cleanBranch -like \"*$BranchSuffix\")) {\n continue\n }\n if ($cleanBranch -match '^(\\d{3})-') {\n $num = [int]$matches[1]\n if ($num -gt $highestFromBranches) { $highestFromBranches = $num }\n }\n }\n }\n } catch {\n Write-Verbose \"Could not check Git branches: $_\"\n }\n $highest = [Math]::Max($highestFromSpecs, $highestFromBranches)\n $next = $highest + 1\n return ('{0:000}' -f $next)\n}\n\n$featureNum = Get-NextFeatureNumber -SpecsDir $specsDir\n", "path": "scripts/powershell/create-new-feature.ps1", "diff_hunk": "@@ -150,6 +150,46 @@ Set-Location $repoRoot\n $specsDir = Join-Path $repoRoot 'specs'\n New-Item -ItemType Directory -Path $specsDir -Force | Out-Null\n \n+# Get highest number from specs directory\n+$highestFromSpecs = 0\n+if (Test-Path $specsDir) {\n+ Get-ChildItem -Path $specsDir -Directory | ForEach-Object {\n+ if ($.Name -match '^(\d{3})') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromSpecs) { $highestFromSpecs = $num }\n+ }\n+ }\n+}\n+\n+# Get highest number from branch names (both local and remote)\n+$highestFromBranches = 0\n+try {\n+ $branches = git branch -a 2>$null\n+ if ($LASTEXITCODE -eq 0) {\n+ foreach ($branch in $branches) {\n+ # Clean branch name: remove leading markers and remote prefixes\n+ # The following regex removes:\n+ # - Git's current branch marker ('') and leading whitespace (e.g., ' main')\n+ # - Remote prefixes (e.g., 'remotes/origin/')\n+ $cleanBranch = $branch.Trim() -replace '^\?\s+', '' -replace '^remotes/[^/]+/', ''\n+ \n+ # Extract feature number if branch matches pattern ###-\n+ if ($cleanBranch -match '^(\d{3})-') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromBranches) { $highestFromBranches = $num }\n+ }\n+ }\n+ }\n+} catch {\n+ # If git command fails, just continue with specs-only check\n+ Write-Verbose "Could not check Git branches: $"\n+}\n+\n+# Use the highest number from either source\n+$highest = [Math]::Max($highestFromSpecs, $highestFromBranches)\n+$next = $highest + 1\n+$featureNum = ('{0:000}' -f $next)", "line": null, "start_line": null, "original_line": 191, "original_start_line": 155}, {"text": "@user1:\nThis new feature numbering logic duplicates the existing check_existing_branches function (lines 84-112). The new code at lines 136-176 calculates feature numbers from specs and branches generically, while check_existing_branches does the same but filtered by a specific branch suffix. This creates redundant logic that needs to be maintained in parallel. Consider refactoring check_existing_branches to support both use cases (with and without a suffix filter), or extracting the common logic into a shared helper function.", "path": "scripts/bash/create-new-feature.sh", "diff_hunk": "@@ -133,6 +133,48 @@ cd "$REPO_ROOT"\n SPECS_DIR="$REPO_ROOT/specs"\n mkdir -p "$SPECS_DIR"\n \n+# Get highest number from specs directory\n+HIGHEST_FROM_SPECS=0\n+if [ -d "$SPECS_DIR" ]; then\n+ for dir in "$SPECS_DIR"/; do\n+ [ -d "$dir" ] || continue\n+ dirname=$(basename "$dir")\n+ number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")\n+ number=$((10#$number))\n+ if [ "$number" -gt "$HIGHEST_FROM_SPECS" ]; then HIGHEST_FROM_SPECS=$number; fi\n+ done\n+fi\n+\n+# Get highest number from branch names (both local and remote)\n+HIGHEST_FROM_BRANCHES=0\n+if [ "$HAS_GIT" = true ]; then\n+ # Get all branches (local and remote)\n+ branches=$(git branch -a 2>/dev/null || echo "")\n+ \n+ if [ -n "$branches" ]; then\n+ while IFS= read -r branch; do\n+ # Clean branch name: remove leading markers and remote prefixes\n+ clean_branch=$(echo "$branch" | sed 's/^[ ]//; s|^remotes/[^/]/||')\n+ \n+ # Extract feature number if branch matches pattern ###-\n+ if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then\n+ number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")\n+ number=$((10#$number))\n+ if [ "$number" -gt "$HIGHEST_FROM_BRANCHES" ]; then HIGHEST_FROM_BRANCHES=$number; fi\n+ fi\n+ done <<< "$branches"\n+ fi\n+fi\n+\n+# Use the highest number from either source\n+HIGHEST=$HIGHEST_FROM_SPECS\n+if [ "$HIGHEST_FROM_BRANCHES" -gt "$HIGHEST" ]; then\n+ HIGHEST=$HIGHEST_FROM_BRANCHES\n+fi\n+\n+NEXT=$((HIGHEST + 1))\n+FEATURE_NUM=$(printf "%03d" "$NEXT")", "line": null, "start_line": null, "original_line": 176, "original_start_line": 136}, {"text": "@user1:\n'except' clause does nothing but pass and there is no explanatory comment.\nsuggestion\n except Exception as e:\n # Could not read version from pyproject.toml; fallback to \"unknown\"\n console.print(f\"[yellow]Warning:[/] Failed to read version from pyproject.toml: {e}\")\n", "path": "src/specify_cli/init.py", "diff_hunk": "@@ -1202,6 +1264,85 @@ def check():\n if not any(agent_results.values()):\n console.print("[dim]Tip: Install an AI assistant for the best experience[/dim]")\n \n+@app.command()\n+def version():\n+ """Display version and system information."""\n+ import platform\n+ import importlib.metadata\n+ \n+ show_banner()\n+ \n+ # Get CLI version from package metadata\n+ cli_version = "unknown"\n+ try:\n+ cli_version = importlib.metadata.version("specify-cli")\n+ except Exception:\n+ # Fallback: try reading from pyproject.toml if running from source\n+ try:\n+ import tomllib\n+ pyproject_path = Path(file).parent.parent.parent / "pyproject.toml"\n+ if pyproject_path.exists():\n+ with open(pyproject_path, "rb") as f:\n+ data = tomllib.load(f)\n+ cli_version = data.get("project", {}).get("version", "unknown")\n+ except Exception:\n+ pass", "line": 1289, "start_line": 1288, "original_line": 1289, "original_start_line": 1288}], "merged_commit": "f4fcd82920021250292e9ce36da249c5431c0469", "merged_patch": "diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml\nindex fa20c809d..5b37ed0be 100644\n--- a/.github/workflows/lint.yml\n+++ b/.github/workflows/lint.yml\n@@ -1,4 +1,6 @@\n name: Lint\n+permissions:\n+ contents: read\n \n on:\n push:\ndiff --git a/.github/workflows/scripts/create-release-packages.ps1 b/.github/workflows/scripts/create-release-packages.ps1\nnew file mode 100644\nindex 000000000..f935dbe86\n--- /dev/null\n+++ b/.github/workflows/scripts/create-release-packages.ps1\n@@ -0,0 +1,416 @@\n+#!/usr/bin/env pwsh\n+#requires -Version 7.0\n+\n+<#\n+.SYNOPSIS\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+\n+.DESCRIPTION\n+ create-release-packages.ps1 (workflow-local)\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+ \n+.PARAMETER Version\n+ Version string with leading 'v' (e.g., v0.2.0)\n+\n+.PARAMETER Agents\n+ Comma or space separated subset of agents to build (default: all)\n+ Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q\n+\n+.PARAMETER Scripts\n+ Comma or space separated subset of script types to build (default: both)\n+ Valid scripts: sh, ps\n+\n+.EXAMPLE\n+ .\create-release-packages.ps1 -Version v0.2.0\n+\n+.EXAMPLE\n+ .\create-release-packages.ps1 -Version v0.2.0 -Agents claude,copilot -Scripts sh\n+\n+.EXAMPLE\n+ .\create-release-packages.ps1 -Version v0.2.0 -Agents claude -Scripts ps\n+#>\n+\n+param(\n+ [Parameter(Mandatory=$true, Position=0)]\n+ [string]$Version,\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Agents = "",\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Scripts = ""\n+)\n+\n+$ErrorActionPreference = "Stop"\n+\n+# Validate version format\n+if ($Version -notmatch '^v\d+\.\d+\.\d+$') {\n+ Write-Error "Version must look like v0.0.0"\n+ exit 1\n+}\n+\n+Write-Host "Building release packages for $Version"\n+\n+# Create and use .genreleases directory for all build artifacts\n+$GenReleasesDir = ".genreleases"\n+if (Test-Path $GenReleasesDir) {\n+ Remove-Item -Path $GenReleasesDir -Recurse -Force -ErrorAction SilentlyContinue\n+}\n+New-Item -ItemType Directory -Path $GenReleasesDir -Force | Out-Null\n+\n+function Rewrite-Paths {\n+ param([string]$Content)\n+ \n+ $Content = $Content -replace '(/?)\bmemory/', '.specify/memory/'\n+ $Content = $Content -replace '(/?)\bscripts/', '.specify/scripts/'\n+ $Content = $Content -replace '(/?)\btemplates/', '.specify/templates/'\n+ return $Content\n+}\n+\n+function Generate-Commands {\n+ param(\n+ [string]$Agent,\n+ [string]$Extension,\n+ [string]$ArgFormat,\n+ [string]$OutputDir,\n+ [string]$ScriptVariant\n+ )\n+ \n+ New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null\n+ \n+ $templates = Get-ChildItem -Path "templates/commands/.md" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($template in $templates) {\n+ $name = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)\n+ \n+ # Read file content and normalize line endings\n+ $fileContent = (Get-Content -Path $template.FullName -Raw) -replace "rn", "n\"\n+ \n+ # Extract description from YAML frontmatter\n+ $description = \"\"\n+ if ($fileContent -match '(?m)^description:\\s*(.+)$') {\n+ $description = $matches[1]\n+ }\n+ \n+ # Extract script command from YAML frontmatter\n+ $scriptCommand = \"\"\n+ if ($fileContent -match \"(?m)^\\s*${ScriptVariant}:\\s*(.+)$\") {\n+ $scriptCommand = $matches[1]\n+ }\n+ \n+ if ([string]::IsNullOrEmpty($scriptCommand)) {\n+ Write-Warning \"No script command found for $ScriptVariant in $($template.Name)\"\n+ $scriptCommand = \"(Missing script command for $ScriptVariant)\"\n+ }\n+ \n+ # Extract agent_script command from YAML frontmatter if present\n+ $agentScriptCommand = \"\"\n+ if ($fileContent -match \"(?ms)agent_scripts:.*?^\\s*${ScriptVariant}:\\s*(.+?)$\") {\n+ $agentScriptCommand = $matches[1].Trim()\n+ }\n+ \n+ # Replace {SCRIPT} placeholder with the script command\n+ $body = $fileContent -replace '\\{SCRIPT\\}', $scriptCommand\n+ \n+ # Replace {AGENT_SCRIPT} placeholder with the agent script command if found\n+ if (-not [string]::IsNullOrEmpty($agentScriptCommand)) {\n+ $body = $body -replace '\\{AGENT_SCRIPT\\}', $agentScriptCommand\n+ }\n+ \n+ # Remove the scripts: and agent_scripts: sections from frontmatter\n+ $lines = $body -split \"n"\n+ $outputLines = @()\n+ $inFrontmatter = $false\n+ $skipScripts = $false\n+ $dashCount = 0\n+ \n+ foreach ($line in $lines) {\n+ if ($line -match '^---$') {\n+ $outputLines += $line\n+ $dashCount++\n+ if ($dashCount -eq 1) {\n+ $inFrontmatter = $true\n+ } else {\n+ $inFrontmatter = $false\n+ }\n+ continue\n+ }\n+ \n+ if ($inFrontmatter) {\n+ if ($line -match '^(scripts|agent_scripts):$') {\n+ $skipScripts = $true\n+ continue\n+ }\n+ if ($line -match '^[a-zA-Z].:' -and $skipScripts) {\n+ $skipScripts = $false\n+ }\n+ if ($skipScripts -and $line -match '^\s+') {\n+ continue\n+ }\n+ }\n+ \n+ $outputLines += $line\n+ }\n+ \n+ $body = $outputLines -join "n\"\n+ \n+ # Apply other substitutions\n+ $body = $body -replace '\\{ARGS\\}', $ArgFormat\n+ $body = $body -replace '__AGENT__', $Agent\n+ $body = Rewrite-Paths -Content $body\n+ \n+ # Generate output file based on extension\n+ $outputFile = Join-Path $OutputDir \"speckit.$name.$Extension\"\n+ \n+ switch ($Extension) {\n+ 'toml' {\n+ $body = $body -replace '\\\\', '\\\\'\n+ $output = \"description = "$description\"nnprompt = "\""n$bodyn\""\"\"\n+ Set-Content -Path $outputFile -Value $output -NoNewline\n+ }\n+ 'md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ 'agent.md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ }\n+ }\n+}\n+\n+function Generate-CopilotPrompts {\n+ param(\n+ [string]$AgentsDir,\n+ [string]$PromptsDir\n+ )\n+ \n+ New-Item -ItemType Directory -Path $PromptsDir -Force | Out-Null\n+ \n+ $agentFiles = Get-ChildItem -Path \"$AgentsDir/speckit.*.agent.md\" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($agentFile in $agentFiles) {\n+ $basename = $agentFile.Name -replace '\\.agent\\.md$', ''\n+ $promptFile = Join-Path $PromptsDir \"$basename.prompt.md\"\n+ \n+ $content = @\"\n+---\n+agent: $basename\n+---\n+\"@\n+ Set-Content -Path $promptFile -Value $content\n+ }\n+}\n+\n+function Build-Variant {\n+ param(\n+ [string]$Agent,\n+ [string]$Script\n+ )\n+ \n+ $baseDir = Join-Path $GenReleasesDir \"sdd-${Agent}-package-${Script}\"\n+ Write-Host \"Building $Agent ($Script) package...\"\n+ New-Item -ItemType Directory -Path $baseDir -Force | Out-Null\n+ \n+ # Copy base structure but filter scripts by variant\n+ $specDir = Join-Path $baseDir \".specify\"\n+ New-Item -ItemType Directory -Path $specDir -Force | Out-Null\n+ \n+ # Copy memory directory\n+ if (Test-Path \"memory\") {\n+ Copy-Item -Path \"memory\" -Destination $specDir -Recurse -Force\n+ Write-Host \"Copied memory -> .specify\"\n+ }\n+ \n+ # Only copy the relevant script variant directory\n+ if (Test-Path \"scripts\") {\n+ $scriptsDestDir = Join-Path $specDir \"scripts\"\n+ New-Item -ItemType Directory -Path $scriptsDestDir -Force | Out-Null\n+ \n+ switch ($Script) {\n+ 'sh' {\n+ if (Test-Path \"scripts/bash\") {\n+ Copy-Item -Path \"scripts/bash\" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host \"Copied scripts/bash -> .specify/scripts\"\n+ }\n+ }\n+ 'ps' {\n+ if (Test-Path \"scripts/powershell\") {\n+ Copy-Item -Path \"scripts/powershell\" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host \"Copied scripts/powershell -> .specify/scripts\"\n+ }\n+ }\n+ }\n+ \n+ # Copy any script files that aren't in variant-specific directories\n+ Get-ChildItem -Path \"scripts\" -File -ErrorAction SilentlyContinue | ForEach-Object {\n+ Copy-Item -Path $_.FullName -Destination $scriptsDestDir -Force\n+ }\n+ }\n+ \n+ # Copy templates (excluding commands directory and vscode-settings.json)\n+ if (Test-Path \"templates\") {\n+ $templatesDestDir = Join-Path $specDir \"templates\"\n+ New-Item -ItemType Directory -Path $templatesDestDir -Force | Out-Null\n+ \n+ Get-ChildItem -Path \"templates\" -Recurse -File | Where-Object {\n+ $_.FullName -notmatch 'templates[/\\\\]commands[/\\\\]' -and $_.Name -ne 'vscode-settings.json'\n+ } | ForEach-Object {\n+ $relativePath = $_.FullName.Substring((Resolve-Path \"templates\").Path.Length + 1)\n+ $destFile = Join-Path $templatesDestDir $relativePath\n+ $destFileDir = Split-Path $destFile -Parent\n+ New-Item -ItemType Directory -Path $destFileDir -Force | Out-Null\n+ Copy-Item -Path $_.FullName -Destination $destFile -Force\n+ }\n+ Write-Host \"Copied templates -> .specify/templates\"\n+ }\n+ \n+ # Generate agent-specific command files\n+ switch ($Agent) {\n+ 'claude' {\n+ $cmdDir = Join-Path $baseDir \".claude/commands\"\n+ Generate-Commands -Agent 'claude' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'gemini' {\n+ $cmdDir = Join-Path $baseDir \".gemini/commands\"\n+ Generate-Commands -Agent 'gemini' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path \"agent_templates/gemini/GEMINI.md\") {\n+ Copy-Item -Path \"agent_templates/gemini/GEMINI.md\" -Destination (Join-Path $baseDir \"GEMINI.md\")\n+ }\n+ }\n+ 'copilot' {\n+ $agentsDir = Join-Path $baseDir \".github/agents\"\n+ Generate-Commands -Agent 'copilot' -Extension 'agent.md' -ArgFormat '$ARGUMENTS' -OutputDir $agentsDir -ScriptVariant $Script\n+ \n+ # Generate companion prompt files\n+ $promptsDir = Join-Path $baseDir \".github/prompts\"\n+ Generate-CopilotPrompts -AgentsDir $agentsDir -PromptsDir $promptsDir\n+ \n+ # Create VS Code workspace settings\n+ $vscodeDir = Join-Path $baseDir \".vscode\"\n+ New-Item -ItemType Directory -Path $vscodeDir -Force | Out-Null\n+ if (Test-Path \"templates/vscode-settings.json\") {\n+ Copy-Item -Path \"templates/vscode-settings.json\" -Destination (Join-Path $vscodeDir \"settings.json\")\n+ }\n+ }\n+ 'cursor-agent' {\n+ $cmdDir = Join-Path $baseDir \".cursor/commands\"\n+ Generate-Commands -Agent 'cursor-agent' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'qwen' {\n+ $cmdDir = Join-Path $baseDir \".qwen/commands\"\n+ Generate-Commands -Agent 'qwen' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path \"agent_templates/qwen/QWEN.md\") {\n+ Copy-Item -Path \"agent_templates/qwen/QWEN.md\" -Destination (Join-Path $baseDir \"QWEN.md\")\n+ }\n+ }\n+ 'opencode' {\n+ $cmdDir = Join-Path $baseDir \".opencode/command\"\n+ Generate-Commands -Agent 'opencode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'windsurf' {\n+ $cmdDir = Join-Path $baseDir \".windsurf/workflows\"\n+ Generate-Commands -Agent 'windsurf' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codex' {\n+ $cmdDir = Join-Path $baseDir \".codex/prompts\"\n+ Generate-Commands -Agent 'codex' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'kilocode' {\n+ $cmdDir = Join-Path $baseDir \".kilocode/workflows\"\n+ Generate-Commands -Agent 'kilocode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'auggie' {\n+ $cmdDir = Join-Path $baseDir \".augment/commands\"\n+ Generate-Commands -Agent 'auggie' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'roo' {\n+ $cmdDir = Join-Path $baseDir \".roo/commands\"\n+ Generate-Commands -Agent 'roo' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codebuddy' {\n+ $cmdDir = Join-Path $baseDir \".codebuddy/commands\"\n+ Generate-Commands -Agent 'codebuddy' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'amp' {\n+ $cmdDir = Join-Path $baseDir \".agents/commands\"\n+ Generate-Commands -Agent 'amp' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'q' {\n+ $cmdDir = Join-Path $baseDir \".amazonq/prompts\"\n+ Generate-Commands -Agent 'q' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ }\n+ \n+ # Create zip archive\n+ $zipFile = Join-Path $GenReleasesDir \"spec-kit-template-${Agent}-${Script}-${Version}.zip\"\n+ Compress-Archive -Path \"$baseDir/*\" -DestinationPath $zipFile -Force\n+ Write-Host \"Created $zipFile\"\n+}\n+\n+# Define all agents and scripts\n+$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q')\n+$AllScripts = @('sh', 'ps')\n+\n+function Normalize-List {\n+ param([string]$Input)\n+ \n+ if ([string]::IsNullOrEmpty($Input)) {\n+ return @()\n+ }\n+ \n+ # Split by comma or space and remove duplicates while preserving order\n+ $items = $Input -split '[,\\s]+' | Where-Object { $_ } | Select-Object -Unique\n+ return $items\n+}\n+\n+function Validate-Subset {\n+ param(\n+ [string]$Type,\n+ [string[]]$Allowed,\n+ [string[]]$Items\n+ )\n+ \n+ $ok = $true\n+ foreach ($item in $Items) {\n+ if ($item -notin $Allowed) {\n+ Write-Error \"Unknown $Type '$item' (allowed: $($Allowed -join ', '))\"\n+ $ok = $false\n+ }\n+ }\n+ return $ok\n+}\n+\n+# Determine agent list\n+if (-not [string]::IsNullOrEmpty($Agents)) {\n+ $AgentList = Normalize-List -Input $Agents\n+ if (-not (Validate-Subset -Type 'agent' -Allowed $AllAgents -Items $AgentList)) {\n+ exit 1\n+ }\n+} else {\n+ $AgentList = $AllAgents\n+}\n+\n+# Determine script list\n+if (-not [string]::IsNullOrEmpty($Scripts)) {\n+ $ScriptList = Normalize-List -Input $Scripts\n+ if (-not (Validate-Subset -Type 'script' -Allowed $AllScripts -Items $ScriptList)) {\n+ exit 1\n+ }\n+} else {\n+ $ScriptList = $AllScripts\n+}\n+\n+Write-Host \"Agents: $($AgentList -join ', ')\"\n+Write-Host \"Scripts: $($ScriptList -join ', ')\"\n+\n+# Build all variants\n+foreach ($agent in $AgentList) {\n+ foreach ($script in $ScriptList) {\n+ Build-Variant -Agent $agent -Script $script\n+ }\n+}\n+\n+Write-Host \"nArchives in ${GenReleasesDir}:"\n+Get-ChildItem -Path $GenReleasesDir -Filter "spec-kit-template--${Version}.zip" | ForEach-Object {\n+ Write-Host " $($.Name)"\n+}\ndiff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh\nindex f9d3b1ae1..1b2e53265 100644\n--- a/.github/workflows/scripts/create-release-packages.sh\n+++ b/.github/workflows/scripts/create-release-packages.sh\n@@ -95,12 +95,32 @@ generate_commands() {\n { echo "description = \"$description\""; echo; echo "prompt = \"\"\""; echo "$body"; echo "\"\"\""; } > "$output_dir/speckit.$name.$ext" ;;\n md)\n echo "$body" > "$output_dir/speckit.$name.$ext" ;;\n- prompt.md)\n+ agent.md)\n echo "$body" > "$output_dir/speckit.$name.$ext" ;;\n esac\n done\n }\n \n+generate_copilot_prompts() {\n+ local agents_dir=$1 prompts_dir=$2\n+ mkdir -p "$prompts_dir"\n+ \n+ # Generate a .prompt.md file for each .agent.md file\n+ for agent_file in "$agents_dir"/speckit.*.agent.md; do\n+ [[ -f "$agent_file" ]] || continue\n+ \n+ local basename=$(basename "$agent_file" .agent.md)\n+ local prompt_file="$prompts_dir/${basename}.prompt.md"\n+ \n+ # Create prompt file with agent frontmatter\n+ cat > "$prompt_file" <<EOF\n+---\n+agent: ${basename}\n+---\n+EOF\n+ done\n+}\n+\n build_variant() {\n local agent=$1 script=$2\n local base_dir="$GENRELEASES_DIR/sdd-${agent}-package-${script}"\n@@ -146,8 +166,10 @@ build_variant() {\n generate_commands gemini toml "{{args}}" "$base_dir/.gemini/commands" "$script"\n [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md "$base_dir/GEMINI.md" ;;\n copilot)\n- mkdir -p "$base_dir/.github/prompts"\n- generate_commands copilot prompt.md "\$ARGUMENTS" "$base_dir/.github/prompts" "$script"\n+ mkdir -p "$base_dir/.github/agents"\n+ generate_commands copilot agent.md "\$ARGUMENTS" "$base_dir/.github/agents" "$script"\n+ # Generate companion prompt files\n+ generate_copilot_prompts "$base_dir/.github/agents" "$base_dir/.github/prompts"\n # Create VS Code workspace settings\n mkdir -p "$base_dir/.vscode"\n [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json "$base_dir/.vscode/settings.json"\ndiff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc\nindex a96fd3e6d..d6db02777 100644\n--- a/.markdownlint-cli2.jsonc\n+++ b/.markdownlint-cli2.jsonc\n@@ -20,5 +20,8 @@\n "MD050": {\n "style": "asterisk"\n }\n- }\n+ },\n+ "ignores": [\n+ ".genreleases/"\n+ ]\n }\n\ No newline at end of file\ndiff --git a/AGENTS.md b/AGENTS.md\nindex d34efb673..f7d956bd7 100644\n--- a/AGENTS.md\n+++ b/AGENTS.md\n@@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a\n |-------|-----------|---------|----------|-------------|\n | Claude Code | .claude/commands/ | Markdown | claude | Anthropic's Claude Code CLI |\n | Gemini CLI | .gemini/commands/ | TOML | gemini | Google's Gemini CLI |\n-| GitHub Copilot | .github/prompts/ | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n+| GitHub Copilot | .github/agents/ | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n | Cursor | .cursor/commands/ | Markdown | cursor-agent | Cursor CLI |\n | Qwen Code | .qwen/commands/ | TOML | qwen | Alibaba's Qwen Code CLI |\n | opencode | .opencode/command/ | Markdown | opencode | opencode CLI |\n@@ -325,9 +325,22 @@ Work within integrated development environments:\n \n Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp\n \n+Standard format:\n+\n+markdown\n+---\n+description: \"Command description\"\n+---\n+\n+Command content with {SCRIPT} and $ARGUMENTS placeholders.\n+\n+\n+GitHub Copilot Chat Mode format:\n+\n markdown\n ---\n description: \"Command description\"\n+mode: speckit.command-name\n ---\n \n Command content with {SCRIPT} and $ARGUMENTS placeholders.\n@@ -349,7 +362,7 @@ Command content with {SCRIPT} and {{args}} placeholders.\n \n - **CLI agents**: Usually `.<agent-name>/commands/`\n - **IDE agents**: Follow IDE-specific patterns:\n- - Copilot: `.github/prompts/`\n+ - Copilot: `.github/agents/`\n - Cursor: `.cursor/commands/`\n - Windsurf: `.windsurf/workflows/`\n \ndiff --git a/CHANGELOG.md b/CHANGELOG.md\nindex ea6729145..7e2ac3697 100644\n--- a/CHANGELOG.md\n+++ b/CHANGELOG.md\n@@ -7,6 +7,22 @@ All notable changes to the Specify CLI and templates are documented here.\n The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\n and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n \n+## [0.0.22] - 2025-11-07\n+\n+- Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.\n+- Move to use `AGENTS.md` for Copilot workloads, since it's already supported out-of-the-box.\n+- Adds support for the version command. ([#486](https://github.com/github/spec-kit/issues/486))\n+- Fixes potential bug with the `create-new-feature.ps1` script that ignores existing feature branches when determining next feature number ([#975](https://github.com/github/spec-kit/issues/975))\n+- Add graceful fallback and logging for GitHub API rate-limiting during template fetch ([#970](https://github.com/github/spec-kit/issues/970))\n+\n+## [0.0.21] - 2025-10-21\n+\n+- Fixes [#975](https://github.com/github/spec-kit/issues/975) (thank you [@fgalarraga](https://github.com/fgalarraga)).\n+- Adds support for Amp CLI.\n+- Adds support for VS Code hand-offs and moves prompts to be full-fledged chat modes.\n+- Adds support for `version` command (addresses [#811](https://github.com/github/spec-kit/issues/811) and [#486](https://github.com/github/spec-kit/issues/486), thank you [@mcasalaina](https://github.com/mcasalaina) and [@dentity007](https://github.com/dentity007)).\n+- Adds support for rendering the rate limit errors from the CLI when encountered ([#970](https://github.com/github/spec-kit/issues/970), thank you [@psmman](https://github.com/psmman)).\n+\n ## [0.0.20] - 2025-10-14\n \n ### Added\ndiff --git a/CONTRIBUTING.md b/CONTRIBUTING.md\nindex e5897b383..c413dd018 100644\n--- a/CONTRIBUTING.md\n+++ b/CONTRIBUTING.md\n@@ -70,6 +70,7 @@ To test your templates, commands, and other changes locally, follow these steps:\n 1. **Create release packages**\n \n Run the following command to generate the local packages:\n+\n \n ./.github/workflows/scripts/create-release-packages.sh v1.0.0\n \ndiff --git a/pyproject.toml b/pyproject.toml\nindex 567d48cd4..fb972adc7 100644\n--- a/pyproject.toml\n+++ b/pyproject.toml\n@@ -1,6 +1,6 @@\n [project]\n name = \"specify-cli\"\n-version = \"0.0.20\"\n+version = \"0.0.22\"\n description = \"Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD).\"\n requires-python = \">=3.11\"\n dependencies = [\ndiff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh\nindex 86d9ecf83..8e8bcf6c3 100644\n--- a/scripts/bash/create-new-feature.sh\n+++ b/scripts/bash/create-new-feature.sh\n@@ -80,9 +80,56 @@ find_repo_root() {\n return 1\n }\n \n+# Function to get highest number from specs directory\n+get_highest_from_specs() {\n+ local specs_dir=\"$1\"\n+ local highest=0\n+ \n+ if [ -d \"$specs_dir\" ]; then\n+ for dir in \"$specs_dir\"/*; do\n+ [ -d \"$dir\" ] || continue\n+ dirname=$(basename \"$dir\")\n+ number=$(echo \"$dirname\" | grep -o '^[0-9]\\+' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$highest\" ]; then\n+ highest=$number\n+ fi\n+ done\n+ fi\n+ \n+ echo \"$highest\"\n+}\n+\n+# Function to get highest number from git branches\n+get_highest_from_branches() {\n+ local highest=0\n+ \n+ # Get all branches (local and remote)\n+ branches=$(git branch -a 2>/dev/null || echo \"\")\n+ \n+ if [ -n \"$branches\" ]; then\n+ while IFS= read -r branch; do\n+ # Clean branch name: remove leading markers and remote prefixes\n+ clean_branch=$(echo \"$branch\" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if echo \"$clean_branch\" | grep -q '^[0-9]\\{3\\}-'; then\n+ number=$(echo \"$clean_branch\" | grep -o '^[0-9]\\{3\\}' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$highest\" ]; then\n+ highest=$number\n+ fi\n+ fi\n+ done <<< \"$branches\"\n+ fi\n+ \n+ echo \"$highest\"\n+}\n+\n # Function to check existing branches (local and remote) and return next available number\n check_existing_branches() {\n local short_name=\"$1\"\n+ local specs_dir=\"$2\"\n \n # Fetch all remotes to get latest branch info (suppress errors if no remotes)\n git fetch --all --prune 2>/dev/null || true\n@@ -95,8 +142,8 @@ check_existing_branches() {\n \n # Check specs directory as well\n local spec_dirs=\"\"\n- if [ -d \"$SPECS_DIR\" ]; then\n- spec_dirs=$(find \"$SPECS_DIR\" -maxdepth 1 -type d -name \"[0-9]*-${short_name}\" 2>/dev/null | xargs -n1 basename 2>/dev/null | sed 's/-.*//' | sort -n)\n+ if [ -d \"$specs_dir\" ]; then\n+ spec_dirs=$(find \"$specs_dir\" -maxdepth 1 -type d -name \"[0-9]*-${short_name}\" 2>/dev/null | xargs -n1 basename 2>/dev/null | sed 's/-.*//' | sort -n)\n fi\n \n # Combine all sources and get the highest number\n@@ -111,6 +158,12 @@ check_existing_branches() {\n echo $((max_num + 1))\n }\n \n+# Function to clean and format a branch name\n+clean_branch_name() {\n+ local name=\"$1\"\n+ echo \"$name\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\\+/-/g' | sed 's/^-//' | sed 's/-$//'\n+}\n+\n # Resolve repository root. Prefer git information when available, but fall back\n # to searching for repository markers so the workflow still functions in repositories that\n # were initialised with --no-git.\n@@ -176,14 +229,15 @@ generate_branch_name() {\n echo \"$result\"\n else\n # Fallback to original logic if no meaningful words found\n- echo \"$description\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\\+/-/g' | sed 's/^-//' | sed 's/-$//' | tr '-' '\\n' | grep -v '^$' | head -3 | tr '\\n' '-' | sed 's/-$//'\n+ local cleaned=$(clean_branch_name \"$description\")\n+ echo \"$cleaned\" | tr '-' '\\n' | grep -v '^$' | head -3 | tr '\\n' '-' | sed 's/-$//'\n fi\n }\n \n # Generate branch name\n if [ -n \"$SHORT_NAME\" ]; then\n # Use provided short name, just clean it up\n- BRANCH_SUFFIX=$(echo \"$SHORT_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\\+/-/g' | sed 's/^-//' | sed 's/-$//')\n+ BRANCH_SUFFIX=$(clean_branch_name \"$SHORT_NAME\")\n else\n # Generate from description with smart filtering\n BRANCH_SUFFIX=$(generate_branch_name \"$FEATURE_DESCRIPTION\")\n@@ -193,19 +247,10 @@ fi\n if [ -z \"$BRANCH_NUMBER\" ]; then\n if [ \"$HAS_GIT\" = true ]; then\n # Check existing branches on remotes\n- BRANCH_NUMBER=$(check_existing_branches \"$BRANCH_SUFFIX\")\n+ BRANCH_NUMBER=$(check_existing_branches \"$BRANCH_SUFFIX\" \"$SPECS_DIR\")\n else\n # Fall back to local directory check\n- HIGHEST=0\n- if [ -d \"$SPECS_DIR\" ]; then\n- for dir in \"$SPECS_DIR\"/*; do\n- [ -d \"$dir\" ] || continue\n- dirname=$(basename \"$dir\")\n- number=$(echo \"$dirname\" | grep -o '^[0-9]\\+' || echo \"0\")\n- number=$((10#$number))\n- if [ \"$number\" -gt \"$HIGHEST\" ]; then HIGHEST=$number; fi\n- done\n- fi\n+ HIGHEST=$(get_highest_from_specs \"$SPECS_DIR\")\n BRANCH_NUMBER=$((HIGHEST + 1))\n fi\n fi\ndiff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh\nindex 2a44c68a1..a375bdc99 100644\n--- a/scripts/bash/update-agent-context.sh\n+++ b/scripts/bash/update-agent-context.sh\n@@ -61,7 +61,7 @@ AGENT_TYPE=\"${1:-}\"\n # Agent-specific file paths \n CLAUDE_FILE=\"$REPO_ROOT/CLAUDE.md\"\n GEMINI_FILE=\"$REPO_ROOT/GEMINI.md\"\n-COPILOT_FILE=\"$REPO_ROOT/.github/copilot-instructions.md\"\n+COPILOT_FILE=\"$REPO_ROOT/.github/agents/copilot-instructions.md\"\n CURSOR_FILE=\"$REPO_ROOT/.cursor/rules/specify-rules.mdc\"\n QWEN_FILE=\"$REPO_ROOT/QWEN.md\"\n AGENTS_FILE=\"$REPO_ROOT/AGENTS.md\"\ndiff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1\nindex 4daa6d2c0..351f4e9e7 100644\n--- a/scripts/powershell/create-new-feature.ps1\n+++ b/scripts/powershell/create-new-feature.ps1\n@@ -59,6 +59,46 @@ function Find-RepositoryRoot {\n }\n }\n \n+function Get-HighestNumberFromSpecs {\n+ param([string]$SpecsDir)\n+ \n+ $highest = 0\n+ if (Test-Path $SpecsDir) {\n+ Get-ChildItem -Path $SpecsDir -Directory | ForEach-Object {\n+ if ($_.Name -match '^(\\d+)') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highest) { $highest = $num }\n+ }\n+ }\n+ }\n+ return $highest\n+}\n+\n+function Get-HighestNumberFromBranches {\n+ param()\n+ \n+ $highest = 0\n+ try {\n+ $branches = git branch -a 2>$null\n+ if ($LASTEXITCODE -eq 0) {\n+ foreach ($branch in $branches) {\n+ # Clean branch name: remove leading markers and remote prefixes\n+ $cleanBranch = $branch.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/[^/]+/', ''\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if ($cleanBranch -match '^(\\d+)-') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highest) { $highest = $num }\n+ }\n+ }\n+ }\n+ } catch {\n+ # If git command fails, return 0\n+ Write-Verbose \"Could not check Git branches: $_\"\n+ }\n+ return $highest\n+}\n+\n function Get-NextBranchNumber {\n param(\n [string]$ShortName,\n@@ -127,6 +167,12 @@ function Get-NextBranchNumber {\n # Return next number\n return $maxNum + 1\n }\n+\n+function ConvertTo-CleanBranchName {\n+ param([string]$Name)\n+ \n+ return $Name.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''\n+}\n $fallbackRoot = (Find-RepositoryRoot -StartDir $PSScriptRoot)\n if (-not $fallbackRoot) {\n Write-Error \"Error: Could not determine repository root. Please run this script from within the repository.\"\n@@ -189,7 +235,7 @@ function Get-BranchName {\n return $result\n } else {\n # Fallback to original logic if no meaningful words found\n- $result = $Description.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''\n+ $result = ConvertTo-CleanBranchName -Name $Description\n $fallbackWords = ($result -split '-') | Where-Object { $_ } | Select-Object -First 3\n return [string]::Join('-', $fallbackWords)\n }\n@@ -198,7 +244,7 @@ function Get-BranchName {\n # Generate branch name\n if ($ShortName) {\n # Use provided short name, just clean it up\n- $branchSuffix = $ShortName.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''\n+ $branchSuffix = ConvertTo-CleanBranchName -Name $ShortName\n } else {\n # Generate from description with smart filtering\n $branchSuffix = Get-BranchName -Description $featureDesc\n@@ -211,16 +257,7 @@ if ($Number -eq 0) {\n $Number = Get-NextBranchNumber -ShortName $branchSuffix -SpecsDir $specsDir\n } else {\n # Fall back to local directory check\n- $highest = 0\n- if (Test-Path $specsDir) {\n- Get-ChildItem -Path $specsDir -Directory | ForEach-Object {\n- if ($_.Name -match '^(\\d{3})') {\n- $num = [int]$matches[1]\n- if ($num -gt $highest) { $highest = $num }\n- }\n- }\n- }\n- $Number = $highest + 1\n+ $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1\n }\n }\n \ndiff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1\nindex db6e9f2d7..d0ed582fa 100644\n--- a/scripts/powershell/setup-plan.ps1\n+++ b/scripts/powershell/setup-plan.ps1\n@@ -59,4 +59,3 @@ if ($Json) {\n Write-Output \"BRANCH: $($paths.CURRENT_BRANCH)\"\n Write-Output \"HAS_GIT: $($paths.HAS_GIT)\"\n }\n-\ndiff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1\nindex 695e28b8d..741a55a63 100644\n--- a/scripts/powershell/update-agent-context.ps1\n+++ b/scripts/powershell/update-agent-context.ps1\n@@ -46,7 +46,7 @@ $NEW_PLAN = $IMPL_PLAN\n # Agent file paths\n $CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md'\n $GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md'\n-$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md'\n+$COPILOT_FILE = Join-Path $REPO_ROOT '.github/agents/copilot-instructions.md'\n $CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc'\n $QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md'\n $AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md'\ndiff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py\nindex a33a1c61a..701b3bdca 100644\n--- a/src/specify_cli/__init__.py\n+++ b/src/specify_cli/__init__.py\n@@ -51,6 +51,7 @@\n import readchar\n import ssl\n import truststore\n+from datetime import datetime, timezone\n \n ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)\n client = httpx.Client(verify=ssl_context)\n@@ -64,6 +65,63 @@ def _github_auth_headers(cli_token: str | None = None) -> dict:\n token = _github_token(cli_token)\n return {\"Authorization\": f\"Bearer {token}\"} if token else {}\n \n+def _parse_rate_limit_headers(headers: httpx.Headers) -> dict:\n+ \"\"\"Extract and parse GitHub rate-limit headers.\"\"\"\n+ info = {}\n+ \n+ # Standard GitHub rate-limit headers\n+ if \"X-RateLimit-Limit\" in headers:\n+ info[\"limit\"] = headers.get(\"X-RateLimit-Limit\")\n+ if \"X-RateLimit-Remaining\" in headers:\n+ info[\"remaining\"] = headers.get(\"X-RateLimit-Remaining\")\n+ if \"X-RateLimit-Reset\" in headers:\n+ reset_epoch = int(headers.get(\"X-RateLimit-Reset\", \"0\"))\n+ if reset_epoch:\n+ reset_time = datetime.fromtimestamp(reset_epoch, tz=timezone.utc)\n+ info[\"reset_epoch\"] = reset_epoch\n+ info[\"reset_time\"] = reset_time\n+ info[\"reset_local\"] = reset_time.astimezone()\n+ \n+ # Retry-After header (seconds or HTTP-date)\n+ if \"Retry-After\" in headers:\n+ retry_after = headers.get(\"Retry-After\")\n+ try:\n+ info[\"retry_after_seconds\"] = int(retry_after)\n+ except ValueError:\n+ # HTTP-date format - not implemented, just store as string\n+ info[\"retry_after\"] = retry_after\n+ \n+ return info\n+\n+def _format_rate_limit_error(status_code: int, headers: httpx.Headers, url: str) -> str:\n+ \"\"\"Format a user-friendly error message with rate-limit information.\"\"\"\n+ rate_info = _parse_rate_limit_headers(headers)\n+ \n+ lines = [f\"GitHub API returned status {status_code} for {url}\"]\n+ lines.append(\"\")\n+ \n+ if rate_info:\n+ lines.append(\"[bold]Rate Limit Information:[/bold]\")\n+ if \"limit\" in rate_info:\n+ lines.append(f\" \u2022 Rate Limit: {rate_info['limit']} requests/hour\")\n+ if \"remaining\" in rate_info:\n+ lines.append(f\" \u2022 Remaining: {rate_info['remaining']}\")\n+ if \"reset_local\" in rate_info:\n+ reset_str = rate_info[\"reset_local\"].strftime(\"%Y-%m-%d %H:%M:%S %Z\")\n+ lines.append(f\" \u2022 Resets at: {reset_str}\")\n+ if \"retry_after_seconds\" in rate_info:\n+ lines.append(f\" \u2022 Retry after: {rate_info['retry_after_seconds']} seconds\")\n+ lines.append(\"\")\n+ \n+ # Add troubleshooting guidance\n+ lines.append(\"[bold]Troubleshooting Tips:[/bold]\")\n+ lines.append(\" \u2022 If you're on a shared CI or corporate environment, you may be rate-limited.\")\n+ lines.append(\" \u2022 Consider using a GitHub token via --github-token or the GH_TOKEN/GITHUB_TOKEN\")\n+ lines.append(\" environment variable to increase rate limits.\")\n+ lines.append(\" \u2022 Authenticated requests have a limit of 5,000/hour vs 60/hour for unauthenticated.\")\n+ \n+ return \"\\n\".join(lines)\n+\n # Agent configuration with name, folder, install URL, and CLI tool requirement\n AGENT_CONFIG = {\n \"copilot\": {\n@@ -577,10 +635,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri\n )\n status = response.status_code\n if status != 200:\n- msg = f\"GitHub API returned {status} for {api_url}\"\n+ # Format detailed error message with rate-limit info\n+ error_msg = _format_rate_limit_error(status, response.headers, api_url)\n if debug:\n- msg += f\"\\nResponse headers: {response.headers}\\nBody (truncated 500): {response.text[:500]}\"\n- raise RuntimeError(msg)\n+ error_msg += f\"\\n\\n[dim]Response body (truncated 500):[/dim]\\n{response.text[:500]}\"\n+ raise RuntimeError(error_msg)\n try:\n release_data = response.json()\n except ValueError as je:\n@@ -627,8 +686,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri\n headers=_github_auth_headers(github_token),\n ) as response:\n if response.status_code != 200:\n- body_sample = response.text[:400]\n- raise RuntimeError(f\"Download failed with {response.status_code}\\nHeaders: {response.headers}\\nBody (truncated): {body_sample}\")\n+ # Handle rate-limiting on download as well\n+ error_msg = _format_rate_limit_error(response.status_code, response.headers, download_url)\n+ if debug:\n+ error_msg += f\"\\n\\n[dim]Response body (truncated 400):[/dim]\\n{response.text[:400]}\"\n+ raise RuntimeError(error_msg)\n total_size = int(response.headers.get('content-length', 0))\n with open(zip_path, 'wb') as f:\n if total_size == 0:\n@@ -1202,6 +1264,85 @@ def check():\n if not any(agent_results.values()):\n console.print(\"[dim]Tip: Install an AI assistant for the best experience[/dim]\")\n \n+@app.command()\n+def version():\n+ \"\"\"Display version and system information.\"\"\"\n+ import platform\n+ import importlib.metadata\n+ \n+ show_banner()\n+ \n+ # Get CLI version from package metadata\n+ cli_version = \"unknown\"\n+ try:\n+ cli_version = importlib.metadata.version(\"specify-cli\")\n+ except Exception:\n+ # Fallback: try reading from pyproject.toml if running from source\n+ try:\n+ import tomllib\n+ pyproject_path = Path(__file__).parent.parent.parent / \"pyproject.toml\"\n+ if pyproject_path.exists():\n+ with open(pyproject_path, \"rb\") as f:\n+ data = tomllib.load(f)\n+ cli_version = data.get(\"project\", {}).get(\"version\", \"unknown\")\n+ except Exception:\n+ pass\n+ \n+ # Fetch latest template release version\n+ repo_owner = \"github\"\n+ repo_name = \"spec-kit\"\n+ api_url = f\"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest\"\n+ \n+ template_version = \"unknown\"\n+ release_date = \"unknown\"\n+ \n+ try:\n+ response = client.get(\n+ api_url,\n+ timeout=10,\n+ follow_redirects=True,\n+ headers=_github_auth_headers(),\n+ )\n+ if response.status_code == 200:\n+ release_data = response.json()\n+ template_version = release_data.get(\"tag_name\", \"unknown\")\n+ # Remove 'v' prefix if present\n+ if template_version.startswith(\"v\"):\n+ template_version = template_version[1:]\n+ release_date = release_data.get(\"published_at\", \"unknown\")\n+ if release_date != \"unknown\":\n+ # Format the date nicely\n+ try:\n+ dt = datetime.fromisoformat(release_date.replace('Z', '+00:00'))\n+ release_date = dt.strftime(\"%Y-%m-%d\")\n+ except Exception:\n+ pass\n+ except Exception:\n+ pass\n+\n+ info_table = Table(show_header=False, box=None, padding=(0, 2))\n+ info_table.add_column(\"Key\", style=\"cyan\", justify=\"right\")\n+ info_table.add_column(\"Value\", style=\"white\")\n+\n+ info_table.add_row(\"CLI Version\", cli_version)\n+ info_table.add_row(\"Template Version\", template_version)\n+ info_table.add_row(\"Released\", release_date)\n+ info_table.add_row(\"\", \"\")\n+ info_table.add_row(\"Python\", platform.python_version())\n+ info_table.add_row(\"Platform\", platform.system())\n+ info_table.add_row(\"Architecture\", platform.machine())\n+ info_table.add_row(\"OS Version\", platform.version())\n+\n+ panel = Panel(\n+ info_table,\n+ title=\"[bold cyan]Specify CLI Information[/bold cyan]\",\n+ border_style=\"cyan\",\n+ padding=(1, 2)\n+ )\n+\n+ console.print(panel)\n+ console.print()\n+\n def main():\n app()\n \ndiff --git a/templates/commands/clarify.md b/templates/commands/clarify.md\nindex 9a62dfa74..4de842aa6 100644\n--- a/templates/commands/clarify.md\n+++ b/templates/commands/clarify.md\n@@ -1,5 +1,9 @@\n ---\n description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json --paths-only\n ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly\ndiff --git a/templates/commands/constitution.md b/templates/commands/constitution.md\nindex f557dd17c..cf81f08c2 100644\n--- a/templates/commands/constitution.md\n+++ b/templates/commands/constitution.md\n@@ -1,5 +1,9 @@\n ---\n-description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync\n+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.\n+handoffs: \n+ - label: Build Specification\n+ agent: speckit.specify\n+ prompt: Implement the feature specification based on the updated constitution. I want to build...\n ---\n \n ## User Input\ndiff --git a/templates/commands/implement.md b/templates/commands/implement.md\nindex 38601920d..fde3651e2 100644\n--- a/templates/commands/implement.md\n+++ b/templates/commands/implement.md\n@@ -135,4 +135,3 @@ You **MUST** consider the user input before proceeding (if not empty).\n - Report final status with summary of completed work\n \n Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.\n-\ndiff --git a/templates/commands/plan.md b/templates/commands/plan.md\nindex 7dfe63a2f..147da0afa 100644\n--- a/templates/commands/plan.md\n+++ b/templates/commands/plan.md\n@@ -1,5 +1,13 @@\n ---\n description: Execute the implementation planning workflow using the plan template to generate design artifacts.\n+handoffs: \n+ - label: Create Tasks\n+ agent: speckit.tasks\n+ prompt: Break the plan into tasks\n+ send: true\n+ - label: Create Checklist\n+ agent: speckit.checklist\n+ prompt: Create a checklist for the following domain...\n scripts:\n sh: scripts/bash/setup-plan.sh --json\n ps: scripts/powershell/setup-plan.ps1 -Json\ndiff --git a/templates/commands/specify.md b/templates/commands/specify.md\nindex 69258a8bf..3f0ddb78b 100644\n--- a/templates/commands/specify.md\n+++ b/templates/commands/specify.md\n@@ -1,5 +1,13 @@\n ---\n description: Create or update the feature specification from a natural language feature description.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n+ - label: Clarify Spec Requirements\n+ agent: speckit.clarify\n+ prompt: Clarify specification requirements\n+ send: true\n scripts:\n sh: scripts/bash/create-new-feature.sh --json \"{ARGS}\"\n ps: scripts/powershell/create-new-feature.ps1 -Json \"{ARGS}\"\ndiff --git a/templates/commands/tasks.md b/templates/commands/tasks.md\nindex 4663c1b67..86a766829 100644\n--- a/templates/commands/tasks.md\n+++ b/templates/commands/tasks.md\n@@ -1,5 +1,14 @@\n ---\n description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.\n+handoffs: \n+ - label: Analyze For Consistency\n+ agent: speckit.analyze\n+ prompt: Run a project analysis for consistency\n+ send: true\n+ - label: Implement Project\n+ agent: speckit.implement\n+ prompt: Start the implementation in phases\n+ send: true\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json\n ps: scripts/powershell/check-prerequisites.ps1 -Json\ndiff --git a/templates/commands/taskstoissues.md b/templates/commands/taskstoissues.md\nnew file mode 100644\nindex 000000000..e0f366372\n--- /dev/null\n+++ b/templates/commands/taskstoissues.md\n@@ -0,0 +1,31 @@\n+---\n+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.\n+tools: ['github/github-mcp-server/create_issue']\n+scripts:\n+ sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks\n+ ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks\n+---\n+\n+## User Input\n+\n+text\n+$ARGUMENTS\n+\n+\n+You **MUST** consider the user input before proceeding (if not empty).\n+\n+## Outline\n+\n+1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like \"I'm Groot\", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: \"I'm Groot\").\n+1. From the executed script, extract the path to **tasks**.\n+1. Get the Git remote by running:\n+\n+bash\n+git config --get remote.origin.url\n+\n+\n+**ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL**\n+\n+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.\n+\n+**UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL**\n", "metadata": {"problem_domain": "Bug Fixes", "difficulty": "high", "estimated_review_effort": 4}} {"instance_id": "github__spec-kit-914@315269d", "repo": "github/spec-kit", "language": "Python", "pull_number": 914, "title": "Smart JSON Merging for VS Code Settings `.vscode/settings.json`", "body": "- Smart JSON Merging for VS Code Settings `.vscode/settings.json` is now intelligently merged instead of being overwritten during `specify init --here` or `specify init .`\r\n\r\n - Existing settings are preserved\r\n - New Spec Kit settings are added\r\n - Nested objects are merged recursively\r\n - Prevents accidental loss of custom VS Code workspace configurations\r\n\r\nfix #859 ", "created_at": "2025-10-16T16:17:42Z", "problem_statement": ".vscode/settings.json is overwritten\nLooks like .vscode/settings.json is fully overwritten. Would be good to merge in case the repo already has a .vscode/settings.json.", "hints_text": "Thanks @brentrossen - will actually work on adding that logic in. Appreciate the callout.", "resolved_issues": [{"number": 859, "title": ".vscode/settings.json is overwritten", "body": "Looks like .vscode/settings.json is fully overwritten. Would be good to merge in case the repo already has a .vscode/settings.json."}], "base_commit": "3b000fce4de8ff8dbed8d2bff32d9eecabd8f908", "commit_to_review": {"head_commit": "315269d9a8a7663a98226239d112a153438485a6", "head_commit_message": "- **Smart JSON Merging for VS Code Settings**: `.vscode/settings.json` is now intelligently merged instead of being overwritten during `specify init --here` or `specify init .`\n - Existing settings are preserved\n - New Spec Kit settings are added\n - Nested objects are merged recursively\n - Prevents accidental loss of custom VS Code workspace configurations", "patch_to_review": "diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py\nindex 56a7bf6e0..757e531be 100644\n--- a/src/specify_cli/__init__.py\n+++ b/src/specify_cli/__init__.py\n@@ -485,6 +485,73 @@ def init_git_repo(project_path: Path, quiet: bool = False) -> Tuple[bool, Option\n finally:\n os.chdir(original_cwd)\n \n+def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None):\n+ \"\"\"Handle merging or copying of .vscode/settings.json files.\"\"\"\n+ def log(message, color=\"green\"):\n+ if verbose and not tracker:\n+ console.print(f\"[{color}]{message}[/] {rel_path}\")\n+\n+ try:\n+ with open(sub_item, 'r', encoding='utf-8') as f:\n+ new_settings = json.load(f)\n+\n+ if dest_file.exists():\n+ merged = merge_json_files(dest_file, new_settings, verbose=verbose and not tracker)\n+ with open(dest_file, 'w', encoding='utf-8') as f:\n+ json.dump(merged, f, indent=4)\n+ f.write('\\n')\n+ log(\"Merged:\", \"green\")\n+ else:\n+ shutil.copy2(sub_item, dest_file)\n+ log(\"Copied (no existing settings.json):\", \"blue\")\n+\n+ except Exception as e:\n+ log(f\"Warning: Could not merge, copying instead: {e}\", \"yellow\")\n+ shutil.copy2(sub_item, dest_file)\n+\n+def merge_json_files(existing_path: Path, new_content: dict, verbose: bool = False) -> dict:\n+ \"\"\"Merge new JSON content into existing JSON file.\n+\n+ Performs a deep merge where:\n+ - New keys are added\n+ - Existing keys are preserved unless overwritten by new content\n+ - Nested dictionaries are merged recursively\n+ - Lists and other values are replaced (not merged)\n+\n+ Args:\n+ existing_path: Path to existing JSON file\n+ new_content: New JSON content to merge in\n+ verbose: Whether to print merge details\n+\n+ Returns:\n+ Merged JSON content as dict\n+ \"\"\"\n+ try:\n+ with open(existing_path, 'r', encoding='utf-8') as f:\n+ existing_content = json.load(f)\n+ except (FileNotFoundError, json.JSONDecodeError):\n+ # If file doesn't exist or is invalid, just use new content\n+ return new_content\n+\n+ def deep_merge(base: dict, update: dict) -> dict:\n+ \"\"\"Recursively merge update dict into base dict.\"\"\"\n+ result = base.copy()\n+ for key, value in update.items():\n+ if key in result and isinstance(result[key], dict) and isinstance(value, dict):\n+ # Recursively merge nested dictionaries\n+ result[key] = deep_merge(result[key], value)\n+ else:\n+ # Add new key or replace existing value\n+ result[key] = value\n+ return result\n+\n+ merged = deep_merge(existing_content, new_content)\n+\n+ if verbose:\n+ console.print(f\"[cyan]Merged JSON file:[/cyan] {existing_path.name}\")\n+\n+ return merged\n+\n def download_template_from_github(ai_assistant: str, download_dir: Path, *, script_type: str = \"sh\", verbose: bool = True, show_progress: bool = True, client: httpx.Client = None, debug: bool = False, github_token: str = None) -> Tuple[Path, dict]:\n repo_owner = \"github\"\n repo_name = \"spec-kit\"\n@@ -676,7 +743,11 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_\n rel_path = sub_item.relative_to(item)\n dest_file = dest_path / rel_path\n dest_file.parent.mkdir(parents=True, exist_ok=True)\n- shutil.copy2(sub_item, dest_file)\n+ # Special handling for .vscode/settings.json - merge instead of overwrite\n+ if dest_file.name == \"settings.json\" and dest_file.parent.name == \".vscode\":\n+ handle_vscode_settings(sub_item, dest_file, rel_path, verbose, tracker)\n+ else:\n+ shutil.copy2(sub_item, dest_file)\n else:\n shutil.copytree(item, dest_path)\n else:\n"}, "reference_review_comments": [{"text": "@user1:\nThe function parameters lack type hints. Consider adding type annotations for better code clarity and IDE support.", "path": "src/specify_cli/__init__.py", "diff_hunk": "@@ -485,6 +485,73 @@ def init_git_repo(project_path: Path, quiet: bool = False) -> Tuple[bool, Option\n finally:\n os.chdir(original_cwd)\n \n+def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None):", "line": null, "start_line": null, "original_line": 488, "original_start_line": null}, {"text": "@user1:\nCatching broad `Exception` can mask specific errors. Consider catching more specific exceptions like `json.JSONDecodeError` and `IOError` to handle different failure scenarios appropriately.", "path": "src/specify_cli/__init__.py", "diff_hunk": "@@ -485,6 +485,73 @@ def init_git_repo(project_path: Path, quiet: bool = False) -> Tuple[bool, Option\n finally:\n os.chdir(original_cwd)\n \n+def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None):\n+ \"\"\"Handle merging or copying of .vscode/settings.json files.\"\"\"\n+ def log(message, color=\"green\"):\n+ if verbose and not tracker:\n+ console.print(f\"[{color}]{message}[/] {rel_path}\")\n+\n+ try:\n+ with open(sub_item, 'r', encoding='utf-8') as f:\n+ new_settings = json.load(f)\n+\n+ if dest_file.exists():\n+ merged = merge_json_files(dest_file, new_settings, verbose=verbose and not tracker)\n+ with open(dest_file, 'w', encoding='utf-8') as f:\n+ json.dump(merged, f, indent=4)\n+ f.write('\\n')\n+ log(\"Merged:\", \"green\")\n+ else:\n+ shutil.copy2(sub_item, dest_file)\n+ log(\"Copied (no existing settings.json):\", \"blue\")\n+\n+ except Exception as e:\n+ log(f\"Warning: Could not merge, copying instead: {e}\", \"yellow\")\n+ shutil.copy2(sub_item, dest_file)", "line": 510, "start_line": 508, "original_line": 510, "original_start_line": 508}, {"text": "@user1:\nConsider adding `IOError` or `OSError` to the exception tuple to handle other file access issues (permissions, disk full, etc.) that could occur when reading the existing file.\nsuggestion\n except (FileNotFoundError, json.JSONDecodeError, OSError):\n # If file doesn't exist, is invalid, or other file access error, just use new content\n", "path": "src/specify_cli/__init__.py", "diff_hunk": "@@ -485,6 +485,73 @@ def init_git_repo(project_path: Path, quiet: bool = False) -> Tuple[bool, Option\n finally:\n os.chdir(original_cwd)\n \n+def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None):\n+ \"\"\"Handle merging or copying of .vscode/settings.json files.\"\"\"\n+ def log(message, color=\"green\"):\n+ if verbose and not tracker:\n+ console.print(f\"[{color}]{message}[/] {rel_path}\")\n+\n+ try:\n+ with open(sub_item, 'r', encoding='utf-8') as f:\n+ new_settings = json.load(f)\n+\n+ if dest_file.exists():\n+ merged = merge_json_files(dest_file, new_settings, verbose=verbose and not tracker)\n+ with open(dest_file, 'w', encoding='utf-8') as f:\n+ json.dump(merged, f, indent=4)\n+ f.write('\\n')\n+ log(\"Merged:\", \"green\")\n+ else:\n+ shutil.copy2(sub_item, dest_file)\n+ log(\"Copied (no existing settings.json):\", \"blue\")\n+\n+ except Exception as e:\n+ log(f\"Warning: Could not merge, copying instead: {e}\", \"yellow\")\n+ shutil.copy2(sub_item, dest_file)\n+\n+def merge_json_files(existing_path: Path, new_content: dict, verbose: bool = False) -> dict:\n+ \"\"\"Merge new JSON content into existing JSON file.\n+\n+ Performs a deep merge where:\n+ - New keys are added\n+ - Existing keys are preserved unless overwritten by new content\n+ - Nested dictionaries are merged recursively\n+ - Lists and other values are replaced (not merged)\n+\n+ Args:\n+ existing_path: Path to existing JSON file\n+ new_content: New JSON content to merge in\n+ verbose: Whether to print merge details\n+\n+ Returns:\n+ Merged JSON content as dict\n+ \"\"\"\n+ try:\n+ with open(existing_path, 'r', encoding='utf-8') as f:\n+ existing_content = json.load(f)\n+ except (FileNotFoundError, json.JSONDecodeError):\n+ # If file doesn't exist or is invalid, just use new content", "line": 533, "start_line": 532, "original_line": 533, "original_start_line": 532}], "merged_commit": "8130d98bcc03334e0ec057ce13dddcf2eb536181", "merged_patch": "diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py\nindex 56a7bf6e0..37cba2868 100644\n--- a/src/specify_cli/__init__.py\n+++ b/src/specify_cli/__init__.py\n@@ -485,6 +485,73 @@ def init_git_repo(project_path: Path, quiet: bool = False) -> Tuple[bool, Option\n finally:\n os.chdir(original_cwd)\n \n+def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None) -> None:\n+ \"\"\"Handle merging or copying of .vscode/settings.json files.\"\"\"\n+ def log(message, color=\"green\"):\n+ if verbose and not tracker:\n+ console.print(f\"[{color}]{message}[/] {rel_path}\")\n+\n+ try:\n+ with open(sub_item, 'r', encoding='utf-8') as f:\n+ new_settings = json.load(f)\n+\n+ if dest_file.exists():\n+ merged = merge_json_files(dest_file, new_settings, verbose=verbose and not tracker)\n+ with open(dest_file, 'w', encoding='utf-8') as f:\n+ json.dump(merged, f, indent=4)\n+ f.write('\\n')\n+ log(\"Merged:\", \"green\")\n+ else:\n+ shutil.copy2(sub_item, dest_file)\n+ log(\"Copied (no existing settings.json):\", \"blue\")\n+\n+ except Exception as e:\n+ log(f\"Warning: Could not merge, copying instead: {e}\", \"yellow\")\n+ shutil.copy2(sub_item, dest_file)\n+\n+def merge_json_files(existing_path: Path, new_content: dict, verbose: bool = False) -> dict:\n+ \"\"\"Merge new JSON content into existing JSON file.\n+\n+ Performs a deep merge where:\n+ - New keys are added\n+ - Existing keys are preserved unless overwritten by new content\n+ - Nested dictionaries are merged recursively\n+ - Lists and other values are replaced (not merged)\n+\n+ Args:\n+ existing_path: Path to existing JSON file\n+ new_content: New JSON content to merge in\n+ verbose: Whether to print merge details\n+\n+ Returns:\n+ Merged JSON content as dict\n+ \"\"\"\n+ try:\n+ with open(existing_path, 'r', encoding='utf-8') as f:\n+ existing_content = json.load(f)\n+ except (FileNotFoundError, json.JSONDecodeError):\n+ # If file doesn't exist or is invalid, just use new content\n+ return new_content\n+\n+ def deep_merge(base: dict, update: dict) -> dict:\n+ \"\"\"Recursively merge update dict into base dict.\"\"\"\n+ result = base.copy()\n+ for key, value in update.items():\n+ if key in result and isinstance(result[key], dict) and isinstance(value, dict):\n+ # Recursively merge nested dictionaries\n+ result[key] = deep_merge(result[key], value)\n+ else:\n+ # Add new key or replace existing value\n+ result[key] = value\n+ return result\n+\n+ merged = deep_merge(existing_content, new_content)\n+\n+ if verbose:\n+ console.print(f\"[cyan]Merged JSON file:[/cyan] {existing_path.name}\")\n+\n+ return merged\n+\n def download_template_from_github(ai_assistant: str, download_dir: Path, *, script_type: str = \"sh\", verbose: bool = True, show_progress: bool = True, client: httpx.Client = None, debug: bool = False, github_token: str = None) -> Tuple[Path, dict]:\n repo_owner = \"github\"\n repo_name = \"spec-kit\"\n@@ -676,7 +743,11 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_\n rel_path = sub_item.relative_to(item)\n dest_file = dest_path / rel_path\n dest_file.parent.mkdir(parents=True, exist_ok=True)\n- shutil.copy2(sub_item, dest_file)\n+ # Special handling for .vscode/settings.json - merge instead of overwrite\n+ if dest_file.name == \"settings.json\" and dest_file.parent.name == \".vscode\":\n+ handle_vscode_settings(sub_item, dest_file, rel_path, verbose, tracker)\n+ else:\n+ shutil.copy2(sub_item, dest_file)\n else:\n shutil.copytree(item, dest_path)\n else:\n", "metadata": {"problem_domain": "Code Style, Linting, Formatting Fixes", "difficulty": "medium", "estimated_review_effort": 3}} {"instance_id": "github__spec-kit-124@24ba304", "repo": "github/spec-kit", "language": "Python", "pull_number": 124, "title": "fix: support Claude CLI installed via migrate-installer", "body": "After running `claude migrate-installer`, the Claude executable is moved from PATH to ~/.claude/local/claude. This change updates `check_tool()` to prioritize checking this local path before falling back to PATH lookup.\r\n\r\nclose: #123", "created_at": "2025-09-09T20:39:35Z", "problem_statement": "not compatible with claude after `claude migrate-installer`\n## Background\n\nI used to execute `claude migrate-installer` for auto-upgrading of the claude cli;\n\nwhich would remove the `claude` from $PATH, but add an alias entry to all shell (bash/zsh/etc.)\n\n## What I expected\n\nspeckit could find the correct `claude` executable binary file and complete the init procesure properly\n\n## What I see\n\nspeckit does not works well;\n\n\n$ uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai claude\n Updated https://github.com/github/spec-kit.git (fc8eb0434a0ac7d49be17b574fa104677dc47f0f)\n Built specify-cli @ git+https://github.com/github/spec-kit.git@fc8eb0434a0ac7d49be17b574fa104677dc47f0f\nInstalled 18 packages in 21ms\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2557\n \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u255a\u2588\u2588\u2557 \u2588\u2588\u2554\u255d\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2557 \u255a\u2588\u2588\u2588\u2588\u2554\u255d\n \u255a\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u255d \u2588\u2588\u2554\u2550\u2550\u255d \u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255d \u255a\u2588\u2588\u2554\u255d\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2551\n \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u255d\n\n Spec-Driven Development Toolkit\n\nWarning: Current directory is not empty (22 items)\nTemplate files will be merged with existing content and may overwrite existing files\nDo you want to continue? [y/N]: y\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Specify Project Setup \u2502\n\u2502 Initializing in current directory: cloudflare-tunnel-ingress-controller \u2502\n\u2502 Path: /Users/strrl/playground/GitHub/cloudflare-tunnel-ingress-controller \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\u26a0\ufe0f claude not found\n Install with: Install from: https://docs.anthropic.com/en/docs/claude-code/setup\nError: Claude CLI is required for Claude Code projects\n\nRequired AI tool is missing!\nTip: Use --ignore-agent-tools to skip this check\n\n$ which claude\nclaude: aliased to /Users/strrl/.claude/local/claude\n\n\n## Potential Solution\n\nlet speckit lookup `$HOME/.claude/local/claude`; and it should be more prioritized than other `claude` executables in $PATH, because in a shell environment, alias is preferred over executable;\n\nso speckit should lookup\n\n1. firstly `$HOME/.claude/local/claude`\n2. otherwise, lookup other exectuable in $PATH\n3. throw an error\n\nI could open a PR if this solution looks good to you guys :heart:\n\n## More References\n\nmore info about `claude migrate-installer` https://docs.anthropic.com/en/docs/claude-code/setup#local-installation", "hints_text": "", "resolved_issues": [{"number": 123, "title": "not compatible with claude after `claude migrate-installer`", "body": "## Background\n\nI used to execute `claude migrate-installer` for auto-upgrading of the claude cli;\n\nwhich would remove the `claude` from $PATH, but add an alias entry to all shell (bash/zsh/etc.)\n\n## What I expected\n\nspeckit could find the correct `claude` executable binary file and complete the init procesure properly\n\n## What I see\n\nspeckit does not works well;\n\n\n$ uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai claude\n Updated https://github.com/github/spec-kit.git (fc8eb0434a0ac7d49be17b574fa104677dc47f0f)\n Built specify-cli @ git+https://github.com/github/spec-kit.git@fc8eb0434a0ac7d49be17b574fa104677dc47f0f\nInstalled 18 packages in 21ms\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2557\n \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u255a\u2588\u2588\u2557 \u2588\u2588\u2554\u255d\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2557 \u255a\u2588\u2588\u2588\u2588\u2554\u255d\n \u255a\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u255d \u2588\u2588\u2554\u2550\u2550\u255d \u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255d \u255a\u2588\u2588\u2554\u255d\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2551\n \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u255d\n\n Spec-Driven Development Toolkit\n\nWarning: Current directory is not empty (22 items)\nTemplate files will be merged with existing content and may overwrite existing files\nDo you want to continue? [y/N]: y\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Specify Project Setup \u2502\n\u2502 Initializing in current directory: cloudflare-tunnel-ingress-controller \u2502\n\u2502 Path: /Users/strrl/playground/GitHub/cloudflare-tunnel-ingress-controller \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\u26a0\ufe0f claude not found\n Install with: Install from: https://docs.anthropic.com/en/docs/claude-code/setup\nError: Claude CLI is required for Claude Code projects\n\nRequired AI tool is missing!\nTip: Use --ignore-agent-tools to skip this check\n\n$ which claude\nclaude: aliased to /Users/strrl/.claude/local/claude\n```\n\n## Potential Solution\n\nlet speckit lookup $HOME/.claude/local/claude; and it should be more prioritized than other `claude` executables in $PATH, because in a shell environment, alias is preferred over executable;\n\nso speckit should lookup\n\n1. firstly `$HOME/.claude/local/claude`\n2. otherwise, lookup other exectuable in $PATH\n3. throw an error\n\nI could open a PR if this solution looks good to you guys ❤️\n\n## More References\n\nmore info about `claude migrate-installer` https://docs.anthropic.com/en/docs/claude-code/setup#local-installation\n"}], "base_commit": "fc8eb0434a0ac7d49be17b574fa104677dc47f0f", "commit_to_review": {"head_commit": "24ba30444eb6ae4cce663b4c00d3fefee523c68e", "head_commit_message": "refactor: extract Claude local path to constant for maintainability\n\nExtract the hardcoded Claude CLI local installation path to a constant\nCLAUDE_LOCAL_PATH to improve maintainability and make it easier to update\nif the installation path changes in the future.\n\nCo-Authored-By: Claude noreply@anthropic.com", "patch_to_review": "diff --git a/src/specify_cli/init.py b/src/specify_cli/init.py\nindex aa3cf3c83..0fc068178 100644\n--- a/src/specify_cli/init.py\n+++ b/src/specify_cli/init.py\n@@ -54,6 +54,9 @@\n "gemini": "Gemini CLI"\n }\n \n+# Claude CLI local installation path after migrate-installer\n+CLAUDE_LOCAL_PATH = Path.home() / ".claude" / "local" / "claude"\n+\n # ASCII Art Banner\n BANNER = """\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2557\n@@ -332,6 +335,16 @@ def run_command(cmd: list[str], check_return: bool = True, capture: bool = False\n \n def check_tool(tool: str, install_hint: str) -> bool:\n """Check if a tool is installed."""\n+ \n+ # Special handling for Claude CLI after `claude migrate-installer`\n+ # See: https://github.com/github/spec-kit/issues/123\n+ # The migrate-installer command REMOVES the original executable from PATH\n+ # and creates an alias at ~/.claude/local/claude instead\n+ # This path should be prioritized over other claude executables in PATH\n+ if tool == "claude":\n+ if CLAUDE_LOCAL_PATH.exists() and CLAUDE_LOCAL_PATH.is_file():\n+ return True\n+ \n if shutil.which(tool):\n return True\n else:\n"}, "reference_review_comments": [{"text": "@user1:\nThe URL in the comment references 'github/spec-kit' but this appears to be a different repository. The URL should be updated to match the actual repository where issue #123 exists.\n\n@author:\nthis url is correct;", "path": "src/specify_cli/init.py", "diff_hunk": "@@ -332,6 +335,16 @@ def run_command(cmd: list[str], check_return: bool = True, capture: bool = False\n \n def check_tool(tool: str, install_hint: str) -> bool:\n """Check if a tool is installed."""\n+ \n+ # Special handling for Claude CLI after `claude migrate-installer`\n+ # See: https://github.com/github/spec-kit/issues/123", "line": 340, "start_line": null, "original_line": 340, "original_start_line": null}], "merged_commit": "24ba30444eb6ae4cce663b4c00d3fefee523c68e", "merged_patch": "diff --git a/src/specify_cli/init.py b/src/specify_cli/init.py\nindex aa3cf3c83..0fc068178 100644\n--- a/src/specify_cli/init.py\n+++ b/src/specify_cli/init.py\n@@ -54,6 +54,9 @@\n "gemini": "Gemini CLI"\n }\n \n+# Claude CLI local installation path after migrate-installer\n+CLAUDE_LOCAL_PATH = Path.home() / ".claude" / "local" / "claude"\n+\n # ASCII Art Banner\n BANNER = """\n \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2557\n@@ -332,6 +335,16 @@ def run_command(cmd: list[str], check_return: bool = True, capture: bool = False\n \n def check_tool(tool: str, install_hint: str) -> bool:\n """Check if a tool is installed."""\n+ \n+ # Special handling for Claude CLI after `claude migrate-installer`\n+ # See: https://github.com/github/spec-kit/issues/123\n+ # The migrate-installer command REMOVES the original executable from PATH\n+ # and creates an alias at ~/.claude/local/claude instead\n+ # This path should be prioritized over other claude executables in PATH\n+ if tool == "claude":\n+ if CLAUDE_LOCAL_PATH.exists() and CLAUDE_LOCAL_PATH.is_file():\n+ return True\n+ \n if shutil.which(tool):\n return True\n else:\n", "metadata": {"problem_domain": "Code Refactoring / Architectural Improvement", "difficulty": "medium", "estimated_review_effort": 3}}

[luanzhiwow]

{
"instance_id": "github__spec-kit-986@392f8b7",
"repo": "github/spec-kit",
"language": "Python",
"pull_number": 986,
"title": "(feat): Enhancements to Spec Kit",
"body": "## Description\r\n\r\n- Introduces a smoother hand-off between stages when used with GitHub Copilot in Visual Studio Code. Prompts are now effectively "shortcuts" for chat modes, and chat modes can then hand-off to specific post-production steps.\r\n- Adds support for the version command. (#486)\r\n- Fixes #975\r\n- Fixes #970 \r\n\r\n## Screenshots\r\n\r\n### Hand-offs\r\n\r\n<img width="1138" height="356" alt="image" src="https://github.com/user-attachments/assets/cdd33d9a-0c5b-4638-bd0c-2677ac6b3a98\" />\r\n\r\n<img width="1119" height="481" alt="image" src="https://github.com/user-attachments/assets/fb3b7718-b806-4186-ac68-f249711d960d\" />\r\n\r\n### Version\r\n\r\n<img width="3800" height="677" alt="image" src="https://github.com/user-attachments/assets/6c41a1a5-56e7-43b6-9b99-0f071e6d190e\" />\r\n\r\n\r\n## References\r\n\r\n- https://github.com/microsoft/vscode/issues/261542\r\n- https://github.com/microsoft/vscode/issues/272211\r\n\r\n## Behavior notes\r\n\r\n- There is an unexpected behavior when hand-off occurs, resetting to Agent Mode. This will be fixed by the VS Code team.",
"created_at": "2025-10-21T17:28:23Z",
"problem_statement": "Add graceful fallback and logging for GitHub API rate-limiting during template fetch\nProblem\n- specify init fetches release data and downloads assets from the GitHub Releases API. If the API rate-limits (or returns an unexpected status), the current error output can be terse and does not expose helpful headers like X-RateLimit-Remaining, X-RateLimit-Reset, or the Retry-After header. This makes diagnosing transient network or rate-limit issues harder for users and maintainers.\n\nWhy this helps\n- Displaying the relevant GitHub rate-limit headers and providing a sensible fallback makes failures easier to understand and act on. A fallback can also attempt a short backoff/retry for transient rate-limits and print the time when the client can retry based on X-RateLimit-Reset.\n\nProposed change\n1. Add header-aware error reporting in download_template_from_github (or the HTTP helper used) so that when a non-200 response is received, the error panel includes:\n - status_code and brief reason (already present)\n - X-RateLimit-Limit (if present)\n - X-RateLimit-Remaining (if present)\n - X-RateLimit-Reset (if present)-convert epoch seconds to a human-readable timestamp in the user's local timezone\n - Retry-After (if present)\n\n2. If the response status indicates rate limiting (HTTP 429) or X-RateLimit-Remaining is 0, implement a simple optional retry strategy:\n - If Retry-After exists: sleep for that many seconds and retry once.\n - Else if X-RateLimit-Reset exists: calculate time until reset; if <= 30 seconds, sleep and retry once; otherwise print a message advising the user to retry later (display reset time).\n - Else: do not retry; surface an actionable error with header details and a troubleshooting hint.\n\n3. Improve user-facing message and troubleshooting panel to include the headers and a short guidance text such as:\n - "Tip: If you're on a shared CI or corporate environment, you may be rate-limited. Consider using a GitHub token via --github-token or the GH_TOKEN/GITHUB_TOKEN environment variable to increase rate limits."\n\n4. Optionally add a --retry-on-rate-limit flag to specify init (default: false) to allow users to opt-in to the automatic short retry behavior. The flag could be useful for automation contexts where waiting a few seconds is acceptable.\n\nSuggested patch outline\n- In src/specify_cli/__init__.py inside download_template_from_github:\n - After receiving the HTTP response, capture headers = response.headers.\n - On non-200, create a helpful detail string composed of the status and any present headers listed above.\n - If status is 429 or X-RateLimit-Remaining == '0', follow the retry decision tree described above.\n - Use rich.Panel to display headers and guidance text when raising errors.\n\nTesting notes\n- Unit test: mock github API responses for the following cases and assert behavior/printed output:\n - 200 OK (no change)\n - 403 or 429 with X-RateLimit-Remaining: 0 and X-RateLimit-Reset in near future (simulate retry path)\n - 403 or 429 with Retry-After header (simulate retry path)\n - 403 or 429 with no rate-limit headers (assert no retry and helpful error)\n- Integration test: run download_template_from_github against a local HTTP server that returns rate-limit headers to validate user-visible messages.\n\nYou can use this for additional documentation:\n- Keep retries conservative (single short retry) to avoid long blocking behavior or masking larger rate-limit issues.\n- Prefer explicit guidance to using a GitHub token rather than silently retrying indefinitely.\n\nPotential bug with the create-new-feature.ps1 script that ignores existing feature branches when determining next feature number\n## Description\n\nThe PowerShell script .specify/scripts/powershell/create-new-feature.ps1 only checks the specs/ directory on the current branch to determine the next feature number, but does not check existing branch names. This causes numbering conflicts when working with multiple feature branches that haven't been merged to main.\n\n## Expected Behavior\n\nWhen running the script from main, it should:\n1. Check the specs/ directory for existing spec folders with pattern \\d{3}-*\n2. Also check git branch output for existing branches with pattern \\d{3}-*\n3. Use the highest number found from either source\n4. Increment by 1 to determine the next feature number\n\n## Current Behavior\n\nThe script only checks step 1 (specs directory on current branch). If feature branches exist but haven't been merged to main, the script will reuse feature numbers, creating conflicts.\n\n## Reproduction Steps\n\n1. Initialize a new spec-kit project\n2. From main branch, run the script to create feature 001:\n powershell\n .\\.specify\\scripts\\powershell\\create-new-feature.ps1 -ShortName \"first-feature\"\n \n - Creates branch 001-first-feature\n - Creates specs/001-first-feature/ directory\n3. Push branch 001-first-feature to remote (do NOT merge to main)\n4. Checkout main again\n5. Run the script to create feature 002:\n powershell\n .\\.specify\\scripts\\powershell\\create-new-feature.ps1 -ShortName \"second-feature\"\n \n\nExpected: Creates branch 002-second-feature \nActual: Creates branch 001-second-feature (reuses 001)\n\n## Root Cause\n\nLooking at lines 82-92 of create-new-feature.ps1:\n\npowershell\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $_.Name -match '^\\d{3}' } |\n ForEach-Object {\n if ($_.Name -match '^(\\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n\nThe script only checks directories in $specsDir, not branch names via git branch.\n\n## Suggested Fix\n\nAdd branch checking logic before determining feature number:\n\npowershell\n# Get highest number from specs directory\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $_.Name -match '^\\d{3}' } |\n ForEach-Object {\n if ($_.Name -match '^(\\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Get highest number from branch names\n$existingBranches = git branch -a | \n ForEach-Object { $_.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/origin/', '' } |\n Where-Object { $_ -match '^\\d{3}-' } |\n ForEach-Object {\n if ($_ -match '^(\\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Use the highest number from either source\n$highestExisting = [Math]::Max(\n $(if ($existingSpecs) { $existingSpecs } else { 0 }),\n $(if ($existingBranches) { $existingBranches } else { 0 })\n)\n\n$featureNumber = $highestExisting + 1\n\n\n## Workaround\n\nUntil fixed, merge spec directories to main after creating each feature branch, so the next run can see the previous feature number in the specs directory.\n\n## Environment\n\n- OS: Windows 11\n- PowerShell Version: 7.5.4\n- spec-kit: v0.0.20",
"hints_text": "I like the idea of adding concrete error messages about rate limits, but don't want to bake in too much logic for retries - that's not the purpose of the CLI, and if all goes south anyway might as well just download the templates from the repo directly and extract them in the folder.\nThat sounds good to me and thanks for linking it to #986 - appreciate that! \n## ✅ Fix Verified and Tested\n\nI can confirm the proposed fix works correctly! Here are the test results:\n\n### Test Setup\n\n1. Applied the suggested fix to create-new-feature.ps1 (checking both specs/ directory AND git branches)\n2. Committed the fix to a fix/branch-numbering-detection branch\n3. Merged the fix to main branch\n4. Ran sequential feature creation tests\n\n### Test Results\n\nTest 1 - Create First Feature:\npowershell\n# From main branch\n/speckit.specify -ShortName \"first-feature\" Create a test feature to verify branch numbering\n\n- ✅ Created branch: 001-first-feature\n- ✅ Committed and pushed to remote\n- ✅ Returned to main branch\n\nTest 2 - Create Second Feature (The Critical Test):\npowershell\n# From main branch (001-first-feature exists ONLY on remote, not merged to main)\n/speckit.specify -ShortName \"second-feature\" Create another test feature to verify incremental numbering\n\n- ✅ Created branch: 002-second-feature (NOT 001-second-feature)\n- ✅ Correctly detected the existing 001-first-feature branch on remote\n- ✅ Incremented to 002 as expected\n\n### Fix Confirmation\n\nThe fix successfully:\n- ✅ Detects existing feature branches from remote repository\n- ✅ Prevents duplicate branch numbers\n- ✅ Works correctly even when feature branches haven't been merged to main\n- ✅ Checks both specs/ directory AND branch names\n- ✅ Uses the highest number from either source\n\n### Implementation Details\n\nThe fix adds branch detection logic that:\n\n1. Scans all branches (local and remote) using git branch -a\n2. Strips remote prefixes (remotes/origin/)\n3. Extracts numeric prefixes matching ^\\d{3}- pattern\n4. Compares highest number from branches vs. specs/ directory\n5. Uses [Math]::Max() to determine the starting point\n6. Increments by 1\n\n### Code Added\n\npowershell\n# Get highest number from branch names\n$existingBranches = git branch -a | \n ForEach-Object { $_.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/origin/', '' } |\n Where-Object { $_ -match '^\\d{3}-' } |\n ForEach-Object {\n if ($_ -match '^(\\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Use the highest number from either source\n$highestExisting = [Math]::Max(\n $(if ($existingSpecs) { $existingSpecs } else { 0 }),\n $(if ($existingBranches) { $existingBranches } else { 0 })\n)\n\n$featureNumber = $highestExisting + 1\n\n\nThis fix resolves the issue completely and enables the proper workflow of creating multiple feature branches in parallel without requiring merges to main for correct numbering.\n\nHI there, i think this won't completly fix the problem with the branch numbering when using coding agents because the speckit.specify command prompt template instructs the agent to call the script with the Number parameter which bypasses this solution.\nI suggest to update the git commands in https://github.com/github/spec-kit/blob/main/templates/commands/specify.md aswell.\n### Template (Source)\n b. Find the highest feature number across all sources for the short-name:\n - Remote branches: git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'\n - Local branches: git branch | grep -E '^[* ]*[0-9]+-<short-name>$'\n - Specs directories: Check for directories matching specs/[0-9]+-<short-name>``\n\n### Template (fix)\n b. Find the highest feature number across all sources for the short-name:\n - Remote branches: git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-$'\n - Local branches: git branch | grep -E '^[* ][0-9]+-$'\n - Specs directories: Check for directories matching specs/[0-9]+-\n\nAm i correct?", "resolved_issues": [ { "number": 970, "title": "Add graceful fallback and logging for GitHub API rate-limiting during template fetch", "body": "Problem\n- specify initfetches release data and downloads assets from the GitHub Releases API. If the API rate-limits (or returns an unexpected status), the current error output can be terse and does not expose helpful headers likeX-RateLimit-Remaining, X-RateLimit-Reset, or the Retry-Afterheader. This makes diagnosing transient network or rate-limit issues harder for users and maintainers.\n\nWhy this helps\n- Displaying the relevant GitHub rate-limit headers and providing a sensible fallback makes failures easier to understand and act on. A fallback can also attempt a short backoff/retry for transient rate-limits and print the time when the client can retry based onX-RateLimit-Reset.\n\nProposed change\n1. Add header-aware error reporting in download_template_from_github(or the HTTP helper used) so that when a non-200 response is received, the error panel includes:\n -status_codeand brief reason (already present)\n -X-RateLimit-Limit(if present)\n -X-RateLimit-Remaining(if present)\n -X-RateLimit-Reset(if present)-convert epoch seconds to a human-readable timestamp in the user's local timezone\n -Retry-After(if present)\n\n2. If the response status indicates rate limiting (HTTP 429) orX-RateLimit-Remainingis0, implement a simple optional retry strategy:\n - If Retry-Afterexists: sleep for that many seconds and retry once.\n - Else ifX-RateLimit-Resetexists: calculate time until reset; if <= 30 seconds, sleep and retry once; otherwise print a message advising the user to retry later (display reset time).\n - Else: do not retry; surface an actionable error with header details and a troubleshooting hint.\n\n3. Improve user-facing message and troubleshooting panel to include the headers and a short guidance text such as:\n - \"Tip: If you're on a shared CI or corporate environment, you may be rate-limited. Consider using a GitHub token via--github-tokenor theGH_TOKEN/GITHUB_TOKENenvironment variable to increase rate limits.\"\n\n4. Optionally add a--retry-on-rate-limitflag tospecify init(default: false) to allow users to opt-in to the automatic short retry behavior. The flag could be useful for automation contexts where waiting a few seconds is acceptable.\n\nSuggested patch outline\n- Insrc/specify_cli/init.pyinsidedownload_template_from_github:\n - After receiving the HTTP response, capture headers = response.headers.\n - On non-200, create a helpful detailstring composed of the status and any present headers listed above.\n - If status is 429 orX-RateLimit-Remaining == '0', follow the retry decision tree described above.\n - Use rich.Panelto display headers and guidance text when raising errors.\n\nTesting notes\n- Unit test: mock github API responses for the following cases and assert behavior/printed output:\n - 200 OK (no change)\n - 403 or 429 withX-RateLimit-Remaining: 0andX-RateLimit-Resetin near future (simulate retry path)\n - 403 or 429 withRetry-Afterheader (simulate retry path)\n - 403 or 429 with no rate-limit headers (assert no retry and helpful error)\n- Integration test: rundownload_template_from_githubagainst a local HTTP server that returns rate-limit headers to validate user-visible messages.\n\nYou can use this for additional documentation:\n- Keep retries conservative _(single short retry)_ to avoid long blocking behavior or masking larger rate-limit issues.\n- Prefer explicit guidance to using a GitHub token rather than silently retrying indefinitely." }, { "number": 975, "title": "Potential bug with the create-new-feature.ps1 script that ignores existing feature branches when determining next feature number", "body": "## Description\n\nThe PowerShell script.specify/scripts/powershell/create-new-feature.ps1only checks thespecs/directory on the current branch to determine the next feature number, but does not check existing branch names. This causes numbering conflicts when working with multiple feature branches that haven't been merged to main.\n\n## Expected Behavior\n\nWhen running the script frommain, it should:\n1. Check the specs/directory for existing spec folders with pattern\d{3}-\n2. **Also check git branchoutput for existing branches with pattern\d{3}-**\n3. Use the highest number found from either source\n4. Increment by 1 to determine the next feature number\n\n## Current Behavior\n\nThe script only checks step 1 (specs directory on current branch). If feature branches exist but haven't been merged to main, the script will reuse feature numbers, creating conflicts.\n\n## Reproduction Steps\n\n1. Initialize a new spec-kit project\n2. From mainbranch, run the script to create feature 001:\n ```powershell\n .\\.specify\\scripts\\powershell\\create-new-feature.ps1 -ShortName \"first-feature\"\n ```\n - Creates branch001-first-feature\n - Creates specs/001-first-feature/directory\n3. Push branch001-first-featureto remote (do NOT merge to main)\n4. Checkoutmainagain\n5. Run the script to create feature 002:\n ```powershell\n .\\.specify\\scripts\\powershell\\create-new-feature.ps1 -ShortName \"second-feature\"\n ```\n\n**Expected**: Creates branch002-second-feature \n**Actual**: Creates branch001-second-feature(reuses 001)\n\n## Root Cause\n\nLooking at lines 82-92 ofcreate-new-feature.ps1:\n\n```powershell\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $_.Name -match '^\\d{3}' } |\n ForEach-Object {\n if ($_.Name -match '^(\\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n```\n\nThe script only checks directories in $specsDir, not branch names via git branch.\n\n## Suggested Fix\n\nAdd branch checking logic before determining feature number:\n\n```powershell\n# Get highest number from specs directory\n$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |\n Where-Object { $_.Name -match '^\\d{3}' } |\n ForEach-Object {\n if ($_.Name -match '^(\\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Get highest number from branch names\n$existingBranches = git branch -a | \n ForEach-Object { $_.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/origin/', '' } |\n Where-Object { $_ -match '^\\d{3}-' } |\n ForEach-Object {\n if ($_ -match '^(\\d{3})') {\n [int]$matches[1]\n }\n } |\n Sort-Object -Descending |\n Select-Object -First 1\n\n# Use the highest number from either source\n$highestExisting = [Math]::Max(\n $(if ($existingSpecs) { $existingSpecs } else { 0 }),\n $(if ($existingBranches) { $existingBranches } else { 0 })\n)\n\n$featureNumber = $highestExisting + 1\n```\n\n## Workaround\n\nUntil fixed, merge spec directories to main after creating each feature branch, so the next run can see the previous feature number in the specs directory.\n\n## Environment\n\n- **OS**: Windows 11\n- **PowerShell Version**: 7.5.4\n- **spec-kit**: v0.0.20" } ], "base_commit": "e6d6f3cdee99752baee578896797400a72430ec0", "commit_to_review": { "head_commit": "392f8b7dfaba5d1d912f268d2830307da584b20f", "head_commit_message": "Update templates/commands/taskstoissues.md\n\nCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>", "patch_to_review": "diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml\nindex fa20c809d..5b37ed0be 100644\n--- a/.github/workflows/lint.yml\n+++ b/.github/workflows/lint.yml\n@@ -1,4 +1,6 @@\n name: Lint\n+permissions:\n+ contents: read\n \n on:\n push:\ndiff --git a/.github/workflows/scripts/create-release-packages.ps1 b/.github/workflows/scripts/create-release-packages.ps1\nnew file mode 100644\nindex 000000000..f935dbe86\n--- /dev/null\n+++ b/.github/workflows/scripts/create-release-packages.ps1\n@@ -0,0 +1,416 @@\n+#!/usr/bin/env pwsh\n+#requires -Version 7.0\n+\n+<#\n+.SYNOPSIS\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+\n+.DESCRIPTION\n+ create-release-packages.ps1 (workflow-local)\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+ \n+.PARAMETER Version\n+ Version string with leading 'v' (e.g., v0.2.0)\n+\n+.PARAMETER Agents\n+ Comma or space separated subset of agents to build (default: all)\n+ Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q\n+\n+.PARAMETER Scripts\n+ Comma or space separated subset of script types to build (default: both)\n+ Valid scripts: sh, ps\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0 -Agents claude,copilot -Scripts sh\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0 -Agents claude -Scripts ps\n+#>\n+\n+param(\n+ [Parameter(Mandatory=$true, Position=0)]\n+ [string]$Version,\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Agents = \"\",\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Scripts = \"\"\n+)\n+\n+$ErrorActionPreference = \"Stop\"\n+\n+# Validate version format\n+if ($Version -notmatch '^v\\d+\\.\\d+\\.\\d+$') {\n+ Write-Error \"Version must look like v0.0.0\"\n+ exit 1\n+}\n+\n+Write-Host \"Building release packages for $Version\"\n+\n+# Create and use .genreleases directory for all build artifacts\n+$GenReleasesDir = \".genreleases\"\n+if (Test-Path $GenReleasesDir) {\n+ Remove-Item -Path $GenReleasesDir -Recurse -Force -ErrorAction SilentlyContinue\n+}\n+New-Item -ItemType Directory -Path $GenReleasesDir -Force | Out-Null\n+\n+function Rewrite-Paths {\n+ param([string]$Content)\n+ \n+ $Content = $Content -replace '(/?)\\bmemory/', '.specify/memory/'\n+ $Content = $Content -replace '(/?)\\bscripts/', '.specify/scripts/'\n+ $Content = $Content -replace '(/?)\\btemplates/', '.specify/templates/'\n+ return $Content\n+}\n+\n+function Generate-Commands {\n+ param(\n+ [string]$Agent,\n+ [string]$Extension,\n+ [string]$ArgFormat,\n+ [string]$OutputDir,\n+ [string]$ScriptVariant\n+ )\n+ \n+ New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null\n+ \n+ $templates = Get-ChildItem -Path \"templates/commands/*.md\" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($template in $templates) {\n+ $name = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)\n+ \n+ # Read file content and normalize line endings\n+ $fileContent = (Get-Content -Path $template.FullName -Raw) -replace \"rn\", \"n"\n+ \n+ # Extract description from YAML frontmatter\n+ $description = ""\n+ if ($fileContent -match '(?m)^description:\s(.+)$') {\n+ $description = $matches[1]\n+ }\n+ \n+ # Extract script command from YAML frontmatter\n+ $scriptCommand = ""\n+ if ($fileContent -match "(?m)^\s*${ScriptVariant}:\s*(.+)$") {\n+ $scriptCommand = $matches[1]\n+ }\n+ \n+ if ([string]::IsNullOrEmpty($scriptCommand)) {\n+ Write-Warning "No script command found for $ScriptVariant in $($template.Name)"\n+ $scriptCommand = "(Missing script command for $ScriptVariant)"\n+ }\n+ \n+ # Extract agent_script command from YAML frontmatter if present\n+ $agentScriptCommand = ""\n+ if ($fileContent -match "(?ms)agent_scripts:.?^\s${ScriptVariant}:\s*(.+?)$") {\n+ $agentScriptCommand = $matches[1].Trim()\n+ }\n+ \n+ # Replace {SCRIPT} placeholder with the script command\n+ $body = $fileContent -replace '\{SCRIPT\}', $scriptCommand\n+ \n+ # Replace {AGENT_SCRIPT} placeholder with the agent script command if found\n+ if (-not [string]::IsNullOrEmpty($agentScriptCommand)) {\n+ $body = $body -replace '\{AGENT_SCRIPT\}', $agentScriptCommand\n+ }\n+ \n+ # Remove the scripts: and agent_scripts: sections from frontmatter\n+ $lines = $body -split "n\"\n+ $outputLines = @()\n+ $inFrontmatter = $false\n+ $skipScripts = $false\n+ $dashCount = 0\n+ \n+ foreach ($line in $lines) {\n+ if ($line -match '^---$') {\n+ $outputLines += $line\n+ $dashCount++\n+ if ($dashCount -eq 1) {\n+ $inFrontmatter = $true\n+ } else {\n+ $inFrontmatter = $false\n+ }\n+ continue\n+ }\n+ \n+ if ($inFrontmatter) {\n+ if ($line -match '^(scripts|agent_scripts):$') {\n+ $skipScripts = $true\n+ continue\n+ }\n+ if ($line -match '^[a-zA-Z].*:' -and $skipScripts) {\n+ $skipScripts = $false\n+ }\n+ if ($skipScripts -and $line -match '^\\s+') {\n+ continue\n+ }\n+ }\n+ \n+ $outputLines += $line\n+ }\n+ \n+ $body = $outputLines -join \"n"\n+ \n+ # Apply other substitutions\n+ $body = $body -replace '\{ARGS\}', $ArgFormat\n+ $body = $body -replace 'AGENT', $Agent\n+ $body = Rewrite-Paths -Content $body\n+ \n+ # Generate output file based on extension\n+ $outputFile = Join-Path $OutputDir "speckit.$name.$Extension"\n+ \n+ switch ($Extension) {\n+ 'toml' {\n+ $body = $body -replace '\\', '\\'\n+ $output = "description = \"$description"nnprompt = \""\"n$bodyn"\"""\n+ Set-Content -Path $outputFile -Value $output -NoNewline\n+ }\n+ 'md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ 'agent.md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ }\n+ }\n+}\n+\n+function Generate-CopilotPrompts {\n+ param(\n+ [string]$AgentsDir,\n+ [string]$PromptsDir\n+ )\n+ \n+ New-Item -ItemType Directory -Path $PromptsDir -Force | Out-Null\n+ \n+ $agentFiles = Get-ChildItem -Path "$AgentsDir/speckit..agent.md" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($agentFile in $agentFiles) {\n+ $basename = $agentFile.Name -replace '\.agent\.md$', ''\n+ $promptFile = Join-Path $PromptsDir "$basename.prompt.md"\n+ \n+ $content = @"\n+---\n+agent: $basename\n+---\n+"@\n+ Set-Content -Path $promptFile -Value $content\n+ }\n+}\n+\n+function Build-Variant {\n+ param(\n+ [string]$Agent,\n+ [string]$Script\n+ )\n+ \n+ $baseDir = Join-Path $GenReleasesDir "sdd-${Agent}-package-${Script}"\n+ Write-Host "Building $Agent ($Script) package..."\n+ New-Item -ItemType Directory -Path $baseDir -Force | Out-Null\n+ \n+ # Copy base structure but filter scripts by variant\n+ $specDir = Join-Path $baseDir ".specify"\n+ New-Item -ItemType Directory -Path $specDir -Force | Out-Null\n+ \n+ # Copy memory directory\n+ if (Test-Path "memory") {\n+ Copy-Item -Path "memory" -Destination $specDir -Recurse -Force\n+ Write-Host "Copied memory -> .specify"\n+ }\n+ \n+ # Only copy the relevant script variant directory\n+ if (Test-Path "scripts") {\n+ $scriptsDestDir = Join-Path $specDir "scripts"\n+ New-Item -ItemType Directory -Path $scriptsDestDir -Force | Out-Null\n+ \n+ switch ($Script) {\n+ 'sh' {\n+ if (Test-Path "scripts/bash") {\n+ Copy-Item -Path "scripts/bash" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host "Copied scripts/bash -> .specify/scripts"\n+ }\n+ }\n+ 'ps' {\n+ if (Test-Path "scripts/powershell") {\n+ Copy-Item -Path "scripts/powershell" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host "Copied scripts/powershell -> .specify/scripts"\n+ }\n+ }\n+ }\n+ \n+ # Copy any script files that aren't in variant-specific directories\n+ Get-ChildItem -Path "scripts" -File -ErrorAction SilentlyContinue | ForEach-Object {\n+ Copy-Item -Path $.FullName -Destination $scriptsDestDir -Force\n+ }\n+ }\n+ \n+ # Copy templates (excluding commands directory and vscode-settings.json)\n+ if (Test-Path "templates") {\n+ $templatesDestDir = Join-Path $specDir "templates"\n+ New-Item -ItemType Directory -Path $templatesDestDir -Force | Out-Null\n+ \n+ Get-ChildItem -Path "templates" -Recurse -File | Where-Object {\n+ $.FullName -notmatch 'templates[/\\]commands[/\\]' -and $.Name -ne 'vscode-settings.json'\n+ } | ForEach-Object {\n+ $relativePath = $.FullName.Substring((Resolve-Path "templates").Path.Length + 1)\n+ $destFile = Join-Path $templatesDestDir $relativePath\n+ $destFileDir = Split-Path $destFile -Parent\n+ New-Item -ItemType Directory -Path $destFileDir -Force | Out-Null\n+ Copy-Item -Path $_.FullName -Destination $destFile -Force\n+ }\n+ Write-Host "Copied templates -> .specify/templates"\n+ }\n+ \n+ # Generate agent-specific command files\n+ switch ($Agent) {\n+ 'claude' {\n+ $cmdDir = Join-Path $baseDir ".claude/commands"\n+ Generate-Commands -Agent 'claude' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'gemini' {\n+ $cmdDir = Join-Path $baseDir ".gemini/commands"\n+ Generate-Commands -Agent 'gemini' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path "agent_templates/gemini/GEMINI.md") {\n+ Copy-Item -Path "agent_templates/gemini/GEMINI.md" -Destination (Join-Path $baseDir "GEMINI.md")\n+ }\n+ }\n+ 'copilot' {\n+ $agentsDir = Join-Path $baseDir ".github/agents"\n+ Generate-Commands -Agent 'copilot' -Extension 'agent.md' -ArgFormat '$ARGUMENTS' -OutputDir $agentsDir -ScriptVariant $Script\n+ \n+ # Generate companion prompt files\n+ $promptsDir = Join-Path $baseDir ".github/prompts"\n+ Generate-CopilotPrompts -AgentsDir $agentsDir -PromptsDir $promptsDir\n+ \n+ # Create VS Code workspace settings\n+ $vscodeDir = Join-Path $baseDir ".vscode"\n+ New-Item -ItemType Directory -Path $vscodeDir -Force | Out-Null\n+ if (Test-Path "templates/vscode-settings.json") {\n+ Copy-Item -Path "templates/vscode-settings.json" -Destination (Join-Path $vscodeDir "settings.json")\n+ }\n+ }\n+ 'cursor-agent' {\n+ $cmdDir = Join-Path $baseDir ".cursor/commands"\n+ Generate-Commands -Agent 'cursor-agent' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'qwen' {\n+ $cmdDir = Join-Path $baseDir ".qwen/commands"\n+ Generate-Commands -Agent 'qwen' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path "agent_templates/qwen/QWEN.md") {\n+ Copy-Item -Path "agent_templates/qwen/QWEN.md" -Destination (Join-Path $baseDir "QWEN.md")\n+ }\n+ }\n+ 'opencode' {\n+ $cmdDir = Join-Path $baseDir ".opencode/command"\n+ Generate-Commands -Agent 'opencode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'windsurf' {\n+ $cmdDir = Join-Path $baseDir ".windsurf/workflows"\n+ Generate-Commands -Agent 'windsurf' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codex' {\n+ $cmdDir = Join-Path $baseDir ".codex/prompts"\n+ Generate-Commands -Agent 'codex' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'kilocode' {\n+ $cmdDir = Join-Path $baseDir ".kilocode/workflows"\n+ Generate-Commands -Agent 'kilocode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'auggie' {\n+ $cmdDir = Join-Path $baseDir ".augment/commands"\n+ Generate-Commands -Agent 'auggie' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'roo' {\n+ $cmdDir = Join-Path $baseDir ".roo/commands"\n+ Generate-Commands -Agent 'roo' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codebuddy' {\n+ $cmdDir = Join-Path $baseDir ".codebuddy/commands"\n+ Generate-Commands -Agent 'codebuddy' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'amp' {\n+ $cmdDir = Join-Path $baseDir ".agents/commands"\n+ Generate-Commands -Agent 'amp' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'q' {\n+ $cmdDir = Join-Path $baseDir ".amazonq/prompts"\n+ Generate-Commands -Agent 'q' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ }\n+ \n+ # Create zip archive\n+ $zipFile = Join-Path $GenReleasesDir "spec-kit-template-${Agent}-${Script}-${Version}.zip"\n+ Compress-Archive -Path "$baseDir/" -DestinationPath $zipFile -Force\n+ Write-Host "Created $zipFile"\n+}\n+\n+# Define all agents and scripts\n+$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q')\n+$AllScripts = @('sh', 'ps')\n+\n+function Normalize-List {\n+ param([string]$Input)\n+ \n+ if ([string]::IsNullOrEmpty($Input)) {\n+ return @()\n+ }\n+ \n+ # Split by comma or space and remove duplicates while preserving order\n+ $items = $Input -split '[,\s]+' | Where-Object { $_ } | Select-Object -Unique\n+ return $items\n+}\n+\n+function Validate-Subset {\n+ param(\n+ [string]$Type,\n+ [string[]]$Allowed,\n+ [string[]]$Items\n+ )\n+ \n+ $ok = $true\n+ foreach ($item in $Items) {\n+ if ($item -notin $Allowed) {\n+ Write-Error "Unknown $Type '$item' (allowed: $($Allowed -join ', '))"\n+ $ok = $false\n+ }\n+ }\n+ return $ok\n+}\n+\n+# Determine agent list\n+if (-not [string]::IsNullOrEmpty($Agents)) {\n+ $AgentList = Normalize-List -Input $Agents\n+ if (-not (Validate-Subset -Type 'agent' -Allowed $AllAgents -Items $AgentList)) {\n+ exit 1\n+ }\n+} else {\n+ $AgentList = $AllAgents\n+}\n+\n+# Determine script list\n+if (-not [string]::IsNullOrEmpty($Scripts)) {\n+ $ScriptList = Normalize-List -Input $Scripts\n+ if (-not (Validate-Subset -Type 'script' -Allowed $AllScripts -Items $ScriptList)) {\n+ exit 1\n+ }\n+} else {\n+ $ScriptList = $AllScripts\n+}\n+\n+Write-Host "Agents: $($AgentList -join ', ')"\n+Write-Host "Scripts: $($ScriptList -join ', ')"\n+\n+# Build all variants\n+foreach ($agent in $AgentList) {\n+ foreach ($script in $ScriptList) {\n+ Build-Variant -Agent $agent -Script $script\n+ }\n+}\n+\n+Write-Host "nArchives in ${GenReleasesDir}:\"\n+Get-ChildItem -Path $GenReleasesDir -Filter \"spec-kit-template-*-${Version}.zip\" | ForEach-Object {\n+ Write-Host \" $($_.Name)\"\n+}\ndiff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh\nindex f9d3b1ae1..1b2e53265 100644\n--- a/.github/workflows/scripts/create-release-packages.sh\n+++ b/.github/workflows/scripts/create-release-packages.sh\n@@ -95,12 +95,32 @@ generate_commands() {\n { echo \"description = \\\"$description\\\"\"; echo; echo \"prompt = \\\"\\\"\\\"\"; echo \"$body\"; echo \"\\\"\\\"\\\"\"; } > \"$output_dir/speckit.$name.$ext\" ;;\n md)\n echo \"$body\" > \"$output_dir/speckit.$name.$ext\" ;;\n- prompt.md)\n+ agent.md)\n echo \"$body\" > \"$output_dir/speckit.$name.$ext\" ;;\n esac\n done\n }\n \n+generate_copilot_prompts() {\n+ local agents_dir=$1 prompts_dir=$2\n+ mkdir -p \"$prompts_dir\"\n+ \n+ # Generate a .prompt.md file for each .agent.md file\n+ for agent_file in \"$agents_dir\"/speckit.*.agent.md; do\n+ [[ -f \"$agent_file\" ]] || continue\n+ \n+ local basename=$(basename \"$agent_file\" .agent.md)\n+ local prompt_file=\"$prompts_dir/${basename}.prompt.md\"\n+ \n+ # Create prompt file with agent frontmatter\n+ cat > \"$prompt_file\" <<EOF\n+---\n+agent: ${basename}\n+---\n+EOF\n+ done\n+}\n+\n build_variant() {\n local agent=$1 script=$2\n local base_dir=\"$GENRELEASES_DIR/sdd-${agent}-package-${script}\"\n@@ -146,8 +166,10 @@ build_variant() {\n generate_commands gemini toml \"{{args}}\" \"$base_dir/.gemini/commands\" \"$script\"\n [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md \"$base_dir/GEMINI.md\" ;;\n copilot)\n- mkdir -p \"$base_dir/.github/prompts\"\n- generate_commands copilot prompt.md \"\\$ARGUMENTS\" \"$base_dir/.github/prompts\" \"$script\"\n+ mkdir -p \"$base_dir/.github/agents\"\n+ generate_commands copilot agent.md \"\\$ARGUMENTS\" \"$base_dir/.github/agents\" \"$script\"\n+ # Generate companion prompt files\n+ generate_copilot_prompts \"$base_dir/.github/agents\" \"$base_dir/.github/prompts\"\n # Create VS Code workspace settings\n mkdir -p \"$base_dir/.vscode\"\n [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json \"$base_dir/.vscode/settings.json\"\ndiff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc\nindex a96fd3e6d..d6db02777 100644\n--- a/.markdownlint-cli2.jsonc\n+++ b/.markdownlint-cli2.jsonc\n@@ -20,5 +20,8 @@\n \"MD050\": {\n \"style\": \"asterisk\"\n }\n- }\n+ },\n+ \"ignores\": [\n+ \".genreleases/\"\n+ ]\n }\n\\ No newline at end of file\ndiff --git a/AGENTS.md b/AGENTS.md\nindex d34efb673..f7d956bd7 100644\n--- a/AGENTS.md\n+++ b/AGENTS.md\n@@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a\n |-------|-----------|---------|----------|-------------|\n | **Claude Code** | .claude/commands/| Markdown |claude| Anthropic's Claude Code CLI |\n | **Gemini CLI** |.gemini/commands/| TOML |gemini| Google's Gemini CLI |\n-| **GitHub Copilot** |.github/prompts/| Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n+| **GitHub Copilot** |.github/agents/| Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n | **Cursor** |.cursor/commands/| Markdown |cursor-agent| Cursor CLI |\n | **Qwen Code** |.qwen/commands/| TOML |qwen| Alibaba's Qwen Code CLI |\n | **opencode** |.opencode/command/| Markdown |opencode| opencode CLI |\n@@ -325,9 +325,22 @@ Work within integrated development environments:\n \n Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp\n \n+**Standard format:**\n+\n+```markdown\n+---\n+description: \"Command description\"\n+---\n+\n+Command content with {SCRIPT} and $ARGUMENTS placeholders.\n+```\n+\n+**GitHub Copilot Chat Mode format:**\n+\n ```markdown\n ---\n description: \"Command description\"\n+mode: speckit.command-name\n ---\n \n Command content with {SCRIPT} and $ARGUMENTS placeholders.\n@@ -349,7 +362,7 @@ Command content with {SCRIPT} and {{args}} placeholders.\n \n - **CLI agents**: Usually./commands/\n - **IDE agents**: Follow IDE-specific patterns:\n- - Copilot: .github/prompts/\n+ - Copilot: .github/agents/\n - Cursor: .cursor/commands/\n - Windsurf: .windsurf/workflows/\n \ndiff --git a/CHANGELOG.md b/CHANGELOG.md\nindex ea6729145..7e2ac3697 100644\n--- a/CHANGELOG.md\n+++ b/CHANGELOG.md\n@@ -7,6 +7,22 @@ All notable changes to the Specify CLI and templates are documented here.\n The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\n and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n \n+## [0.0.22] - 2025-11-07\n+\n+- Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.\n+- Move to use AGENTS.mdfor Copilot workloads, since it's already supported out-of-the-box.\n+- Adds support for the version command. ([#486](https://github.com/github/spec-kit/issues/486))\n+- Fixes potential bug with thecreate-new-feature.ps1script that ignores existing feature branches when determining next feature number ([#975](https://github.com/github/spec-kit/issues/975))\n+- Add graceful fallback and logging for GitHub API rate-limiting during template fetch ([#970](https://github.com/github/spec-kit/issues/970))\n+\n+## [0.0.21] - 2025-10-21\n+\n+- Fixes [#975](https://github.com/github/spec-kit/issues/975) (thank you [@fgalarraga](https://github.com/fgalarraga)).\n+- Adds support for Amp CLI.\n+- Adds support for VS Code hand-offs and moves prompts to be full-fledged chat modes.\n+- Adds support forversioncommand (addresses [#811](https://github.com/github/spec-kit/issues/811) and [#486](https://github.com/github/spec-kit/issues/486), thank you [@mcasalaina](https://github.com/mcasalaina) and [@dentity007](https://github.com/dentity007)).\n+- Adds support for rendering the rate limit errors from the CLI when encountered ([#970](https://github.com/github/spec-kit/issues/970), thank you [@psmman](https://github.com/psmman)).\n+\n ## [0.0.20] - 2025-10-14\n \n ### Added\ndiff --git a/CONTRIBUTING.md b/CONTRIBUTING.md\nindex e5897b383..c413dd018 100644\n--- a/CONTRIBUTING.md\n+++ b/CONTRIBUTING.md\n@@ -70,6 +70,7 @@ To test your templates, commands, and other changes locally, follow these steps:\n 1. **Create release packages**\n \n Run the following command to generate the local packages:\n+\n ```\n ./.github/workflows/scripts/create-release-packages.sh v1.0.0\n ```\ndiff --git a/pyproject.toml b/pyproject.toml\nindex 567d48cd4..fb972adc7 100644\n--- a/pyproject.toml\n+++ b/pyproject.toml\n@@ -1,6 +1,6 @@\n [project]\n name = \"specify-cli\"\n-version = \"0.0.20\"\n+version = \"0.0.22\"\n description = \"Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD).\"\n requires-python = \">=3.11\"\n dependencies = [\ndiff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh\nindex 86d9ecf83..ed244282b 100644\n--- a/scripts/bash/create-new-feature.sh\n+++ b/scripts/bash/create-new-feature.sh\n@@ -133,6 +133,48 @@ cd \"$REPO_ROOT\"\n SPECS_DIR=\"$REPO_ROOT/specs\"\n mkdir -p \"$SPECS_DIR\"\n \n+# Get highest number from specs directory\n+HIGHEST_FROM_SPECS=0\n+if [ -d \"$SPECS_DIR\" ]; then\n+ for dir in \"$SPECS_DIR\"/*; do\n+ [ -d \"$dir\" ] || continue\n+ dirname=$(basename \"$dir\")\n+ number=$(echo \"$dirname\" | grep -o '^[0-9]\\+' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$HIGHEST_FROM_SPECS\" ]; then HIGHEST_FROM_SPECS=$number; fi\n+ done\n+fi\n+\n+# Get highest number from branch names (both local and remote)\n+HIGHEST_FROM_BRANCHES=0\n+if [ \"$HAS_GIT\" = true ]; then\n+ # Get all branches (local and remote)\n+ branches=$(git branch -a 2>/dev/null || echo \"\")\n+ \n+ if [ -n \"$branches\" ]; then\n+ while IFS= read -r branch; do\n+ # Clean branch name: remove leading markers and remote prefixes\n+ clean_branch=$(echo \"$branch\" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if echo \"$clean_branch\" | grep -q '^[0-9]\\{3\\}-'; then\n+ number=$(echo \"$clean_branch\" | grep -o '^[0-9]\\{3\\}' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$HIGHEST_FROM_BRANCHES\" ]; then HIGHEST_FROM_BRANCHES=$number; fi\n+ fi\n+ done <<< \"$branches\"\n+ fi\n+fi\n+\n+# Use the highest number from either source\n+HIGHEST=$HIGHEST_FROM_SPECS\n+if [ \"$HIGHEST_FROM_BRANCHES\" -gt \"$HIGHEST\" ]; then\n+ HIGHEST=$HIGHEST_FROM_BRANCHES\n+fi\n+\n+NEXT=$((HIGHEST + 1))\n+FEATURE_NUM=$(printf \"%03d\" \"$NEXT\")\n+\n # Function to generate branch name with stop word filtering and length filtering\n generate_branch_name() {\n local description=\"$1\"\ndiff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh\nindex 2a44c68a1..fcb525ac0 100644\n--- a/scripts/bash/update-agent-context.sh\n+++ b/scripts/bash/update-agent-context.sh\n@@ -61,7 +61,8 @@ AGENT_TYPE=\"${1:-}\"\n # Agent-specific file paths \n CLAUDE_FILE=\"$REPO_ROOT/CLAUDE.md\"\n GEMINI_FILE=\"$REPO_ROOT/GEMINI.md\"\n-COPILOT_FILE=\"$REPO_ROOT/.github/copilot-instructions.md\"\n+COPILOT_FILE=\"$REPO_ROOT/.github/agents/copilot-instructions.md\"\n+COPILOT_AGENTS_FILE=\"$REPO_ROOT/AGENTS.md\"\n CURSOR_FILE=\"$REPO_ROOT/.cursor/rules/specify-rules.mdc\"\n QWEN_FILE=\"$REPO_ROOT/QWEN.md\"\n AGENTS_FILE=\"$REPO_ROOT/AGENTS.md\"\n@@ -587,6 +588,7 @@ update_specific_agent() {\n ;;\n copilot)\n update_agent_file \"$COPILOT_FILE\" \"GitHub Copilot\"\n+ update_agent_file \"$COPILOT_AGENTS_FILE\" \"GitHub Copilot (AGENTS.md)\"\n ;;\n cursor-agent)\n update_agent_file \"$CURSOR_FILE\" \"Cursor IDE\"\n@@ -648,6 +650,12 @@ update_all_existing_agents() {\n found_agent=true\n fi\n \n+ # Also update AGENTS.md for Copilot if the Copilot directory exists\n+ if [[ -d \"$REPO_ROOT/.github/agents\" ]]; then\n+ update_agent_file \"$COPILOT_AGENTS_FILE\" \"GitHub Copilot (AGENTS.md)\"\n+ found_agent=true\n+ fi\n+ \n if [[ -f \"$CURSOR_FILE\" ]]; then\n update_agent_file \"$CURSOR_FILE\" \"Cursor IDE\"\n found_agent=true\ndiff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1\nindex 4daa6d2c0..db92c3f77 100644\n--- a/scripts/powershell/create-new-feature.ps1\n+++ b/scripts/powershell/create-new-feature.ps1\n@@ -150,6 +150,46 @@ Set-Location $repoRoot\n $specsDir = Join-Path $repoRoot 'specs'\n New-Item -ItemType Directory -Path $specsDir -Force | Out-Null\n \n+# Get highest number from specs directory\n+$highestFromSpecs = 0\n+if (Test-Path $specsDir) {\n+ Get-ChildItem -Path $specsDir -Directory | ForEach-Object {\n+ if ($_.Name -match '^(\\d{3})') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromSpecs) { $highestFromSpecs = $num }\n+ }\n+ }\n+}\n+\n+# Get highest number from branch names (both local and remote)\n+$highestFromBranches = 0\n+try {\n+ $branches = git branch -a 2>$null\n+ if ($LASTEXITCODE -eq 0) {\n+ foreach ($branch in $branches) {\n+ # Clean branch name: remove leading markers and remote prefixes\n+ # The following regex removes:\n+ # - Git's current branch marker ('*') and leading whitespace (e.g., '* main')\n+ # - Remote prefixes (e.g., 'remotes/origin/')\n+ $cleanBranch = $branch.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/[^/]+/', ''\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if ($cleanBranch -match '^(\\d{3})-') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromBranches) { $highestFromBranches = $num }\n+ }\n+ }\n+ }\n+} catch {\n+ # If git command fails, just continue with specs-only check\n+ Write-Verbose \"Could not check Git branches: $_\"\n+}\n+\n+# Use the highest number from either source\n+$highest = [Math]::Max($highestFromSpecs, $highestFromBranches)\n+$next = $highest + 1\n+$featureNum = ('{0:000}' -f $next)\n+\n # Function to generate branch name with stop word filtering and length filtering\n function Get-BranchName {\n param([string]$Description)\ndiff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1\nindex db6e9f2d7..d0ed582fa 100644\n--- a/scripts/powershell/setup-plan.ps1\n+++ b/scripts/powershell/setup-plan.ps1\n@@ -59,4 +59,3 @@ if ($Json) {\n Write-Output \"BRANCH: $($paths.CURRENT_BRANCH)\"\n Write-Output \"HAS_GIT: $($paths.HAS_GIT)\"\n }\n-\ndiff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1\nindex 695e28b8d..a439cc435 100644\n--- a/scripts/powershell/update-agent-context.ps1\n+++ b/scripts/powershell/update-agent-context.ps1\n@@ -46,7 +46,8 @@ $NEW_PLAN = $IMPL_PLAN\n # Agent file paths\n $CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md'\n $GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md'\n-$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md'\n+$COPILOT_FILE = Join-Path $REPO_ROOT '.github/agents/copilot-instructions.md'\n+$COPILOT_AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md'\n $CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc'\n $QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md'\n $AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md'\n@@ -370,7 +371,10 @@ function Update-SpecificAgent {\n switch ($Type) {\n 'claude' { Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code' }\n 'gemini' { Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI' }\n- 'copilot' { Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot' }\n+ 'copilot' { \n+ Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot'\n+ Update-AgentFile -TargetFile $COPILOT_AGENTS_FILE -AgentName 'GitHub Copilot (AGENTS.md)'\n+ }\n 'cursor-agent' { Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE' }\n 'qwen' { Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code' }\n 'opencode' { Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'opencode' }\n@@ -392,6 +396,8 @@ function Update-AllExistingAgents {\n if (Test-Path $CLAUDE_FILE) { if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false }; $found = $true }\n if (Test-Path $GEMINI_FILE) { if (-not (Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI')) { $ok = $false }; $found = $true }\n if (Test-Path $COPILOT_FILE) { if (-not (Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot')) { $ok = $false }; $found = $true }\n+ # Also update AGENTS.md for Copilot if the Copilot directory exists\n+ if (Test-Path (Join-Path $REPO_ROOT '.github/agents')) { if (-not (Update-AgentFile -TargetFile $COPILOT_AGENTS_FILE -AgentName 'GitHub Copilot (AGENTS.md)')) { $ok = $false }; $found = $true }\n if (Test-Path $CURSOR_FILE) { if (-not (Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE')) { $ok = $false }; $found = $true }\n if (Test-Path $QWEN_FILE) { if (-not (Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code')) { $ok = $false }; $found = $true }\n if (Test-Path $AGENTS_FILE) { if (-not (Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex/opencode')) { $ok = $false }; $found = $true }\ndiff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py\nindex a33a1c61a..701b3bdca 100644\n--- a/src/specify_cli/__init__.py\n+++ b/src/specify_cli/__init__.py\n@@ -51,6 +51,7 @@\n import readchar\n import ssl\n import truststore\n+from datetime import datetime, timezone\n \n ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)\n client = httpx.Client(verify=ssl_context)\n@@ -64,6 +65,63 @@ def _github_auth_headers(cli_token: str | None = None) -> dict:\n token = _github_token(cli_token)\n return {\"Authorization\": f\"Bearer {token}\"} if token else {}\n \n+def _parse_rate_limit_headers(headers: httpx.Headers) -> dict:\n+ \"\"\"Extract and parse GitHub rate-limit headers.\"\"\"\n+ info = {}\n+ \n+ # Standard GitHub rate-limit headers\n+ if \"X-RateLimit-Limit\" in headers:\n+ info[\"limit\"] = headers.get(\"X-RateLimit-Limit\")\n+ if \"X-RateLimit-Remaining\" in headers:\n+ info[\"remaining\"] = headers.get(\"X-RateLimit-Remaining\")\n+ if \"X-RateLimit-Reset\" in headers:\n+ reset_epoch = int(headers.get(\"X-RateLimit-Reset\", \"0\"))\n+ if reset_epoch:\n+ reset_time = datetime.fromtimestamp(reset_epoch, tz=timezone.utc)\n+ info[\"reset_epoch\"] = reset_epoch\n+ info[\"reset_time\"] = reset_time\n+ info[\"reset_local\"] = reset_time.astimezone()\n+ \n+ # Retry-After header (seconds or HTTP-date)\n+ if \"Retry-After\" in headers:\n+ retry_after = headers.get(\"Retry-After\")\n+ try:\n+ info[\"retry_after_seconds\"] = int(retry_after)\n+ except ValueError:\n+ # HTTP-date format - not implemented, just store as string\n+ info[\"retry_after\"] = retry_after\n+ \n+ return info\n+\n+def _format_rate_limit_error(status_code: int, headers: httpx.Headers, url: str) -> str:\n+ \"\"\"Format a user-friendly error message with rate-limit information.\"\"\"\n+ rate_info = _parse_rate_limit_headers(headers)\n+ \n+ lines = [f\"GitHub API returned status {status_code} for {url}\"]\n+ lines.append(\"\")\n+ \n+ if rate_info:\n+ lines.append(\"[bold]Rate Limit Information:[/bold]\")\n+ if \"limit\" in rate_info:\n+ lines.append(f\" • Rate Limit: {rate_info['limit']} requests/hour\")\n+ if \"remaining\" in rate_info:\n+ lines.append(f\" • Remaining: {rate_info['remaining']}\")\n+ if \"reset_local\" in rate_info:\n+ reset_str = rate_info[\"reset_local\"].strftime(\"%Y-%m-%d %H:%M:%S %Z\")\n+ lines.append(f\" • Resets at: {reset_str}\")\n+ if \"retry_after_seconds\" in rate_info:\n+ lines.append(f\" • Retry after: {rate_info['retry_after_seconds']} seconds\")\n+ lines.append(\"\")\n+ \n+ # Add troubleshooting guidance\n+ lines.append(\"[bold]Troubleshooting Tips:[/bold]\")\n+ lines.append(\" • If you're on a shared CI or corporate environment, you may be rate-limited.\")\n+ lines.append(\" • Consider using a GitHub token via --github-token or the GH_TOKEN/GITHUB_TOKEN\")\n+ lines.append(\" environment variable to increase rate limits.\")\n+ lines.append(\" • Authenticated requests have a limit of 5,000/hour vs 60/hour for unauthenticated.\")\n+ \n+ return \"\\n\".join(lines)\n+\n # Agent configuration with name, folder, install URL, and CLI tool requirement\n AGENT_CONFIG = {\n \"copilot\": {\n@@ -577,10 +635,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri\n )\n status = response.status_code\n if status != 200:\n- msg = f\"GitHub API returned {status} for {api_url}\"\n+ # Format detailed error message with rate-limit info\n+ error_msg = _format_rate_limit_error(status, response.headers, api_url)\n if debug:\n- msg += f\"\\nResponse headers: {response.headers}\\nBody (truncated 500): {response.text[:500]}\"\n- raise RuntimeError(msg)\n+ error_msg += f\"\\n\\n[dim]Response body (truncated 500):[/dim]\\n{response.text[:500]}\"\n+ raise RuntimeError(error_msg)\n try:\n release_data = response.json()\n except ValueError as je:\n@@ -627,8 +686,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri\n headers=_github_auth_headers(github_token),\n ) as response:\n if response.status_code != 200:\n- body_sample = response.text[:400]\n- raise RuntimeError(f\"Download failed with {response.status_code}\\nHeaders: {response.headers}\\nBody (truncated): {body_sample}\")\n+ # Handle rate-limiting on download as well\n+ error_msg = _format_rate_limit_error(response.status_code, response.headers, download_url)\n+ if debug:\n+ error_msg += f\"\\n\\n[dim]Response body (truncated 400):[/dim]\\n{response.text[:400]}\"\n+ raise RuntimeError(error_msg)\n total_size = int(response.headers.get('content-length', 0))\n with open(zip_path, 'wb') as f:\n if total_size == 0:\n@@ -1202,6 +1264,85 @@ def check():\n if not any(agent_results.values()):\n console.print(\"[dim]Tip: Install an AI assistant for the best experience[/dim]\")\n \n+@app.command()\n+def version():\n+ \"\"\"Display version and system information.\"\"\"\n+ import platform\n+ import importlib.metadata\n+ \n+ show_banner()\n+ \n+ # Get CLI version from package metadata\n+ cli_version = \"unknown\"\n+ try:\n+ cli_version = importlib.metadata.version(\"specify-cli\")\n+ except Exception:\n+ # Fallback: try reading from pyproject.toml if running from source\n+ try:\n+ import tomllib\n+ pyproject_path = Path(__file__).parent.parent.parent / \"pyproject.toml\"\n+ if pyproject_path.exists():\n+ with open(pyproject_path, \"rb\") as f:\n+ data = tomllib.load(f)\n+ cli_version = data.get(\"project\", {}).get(\"version\", \"unknown\")\n+ except Exception:\n+ pass\n+ \n+ # Fetch latest template release version\n+ repo_owner = \"github\"\n+ repo_name = \"spec-kit\"\n+ api_url = f\"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest\"\n+ \n+ template_version = \"unknown\"\n+ release_date = \"unknown\"\n+ \n+ try:\n+ response = client.get(\n+ api_url,\n+ timeout=10,\n+ follow_redirects=True,\n+ headers=_github_auth_headers(),\n+ )\n+ if response.status_code == 200:\n+ release_data = response.json()\n+ template_version = release_data.get(\"tag_name\", \"unknown\")\n+ # Remove 'v' prefix if present\n+ if template_version.startswith(\"v\"):\n+ template_version = template_version[1:]\n+ release_date = release_data.get(\"published_at\", \"unknown\")\n+ if release_date != \"unknown\":\n+ # Format the date nicely\n+ try:\n+ dt = datetime.fromisoformat(release_date.replace('Z', '+00:00'))\n+ release_date = dt.strftime(\"%Y-%m-%d\")\n+ except Exception:\n+ pass\n+ except Exception:\n+ pass\n+\n+ info_table = Table(show_header=False, box=None, padding=(0, 2))\n+ info_table.add_column(\"Key\", style=\"cyan\", justify=\"right\")\n+ info_table.add_column(\"Value\", style=\"white\")\n+\n+ info_table.add_row(\"CLI Version\", cli_version)\n+ info_table.add_row(\"Template Version\", template_version)\n+ info_table.add_row(\"Released\", release_date)\n+ info_table.add_row(\"\", \"\")\n+ info_table.add_row(\"Python\", platform.python_version())\n+ info_table.add_row(\"Platform\", platform.system())\n+ info_table.add_row(\"Architecture\", platform.machine())\n+ info_table.add_row(\"OS Version\", platform.version())\n+\n+ panel = Panel(\n+ info_table,\n+ title=\"[bold cyan]Specify CLI Information[/bold cyan]\",\n+ border_style=\"cyan\",\n+ padding=(1, 2)\n+ )\n+\n+ console.print(panel)\n+ console.print()\n+\n def main():\n app()\n \ndiff --git a/templates/commands/clarify.md b/templates/commands/clarify.md\nindex 9a62dfa74..4de842aa6 100644\n--- a/templates/commands/clarify.md\n+++ b/templates/commands/clarify.md\n@@ -1,5 +1,9 @@\n ---\n description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json --paths-only\n ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly\ndiff --git a/templates/commands/constitution.md b/templates/commands/constitution.md\nindex f557dd17c..cf81f08c2 100644\n--- a/templates/commands/constitution.md\n+++ b/templates/commands/constitution.md\n@@ -1,5 +1,9 @@\n ---\n-description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync\n+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.\n+handoffs: \n+ - label: Build Specification\n+ agent: speckit.specify\n+ prompt: Implement the feature specification based on the updated constitution. I want to build...\n ---\n \n ## User Input\ndiff --git a/templates/commands/implement.md b/templates/commands/implement.md\nindex 38601920d..fde3651e2 100644\n--- a/templates/commands/implement.md\n+++ b/templates/commands/implement.md\n@@ -135,4 +135,3 @@ You **MUST** consider the user input before proceeding (if not empty).\n - Report final status with summary of completed work\n \n Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running/speckit.tasksfirst to regenerate the task list.\n-\ndiff --git a/templates/commands/plan.md b/templates/commands/plan.md\nindex 7dfe63a2f..147da0afa 100644\n--- a/templates/commands/plan.md\n+++ b/templates/commands/plan.md\n@@ -1,5 +1,13 @@\n ---\n description: Execute the implementation planning workflow using the plan template to generate design artifacts.\n+handoffs: \n+ - label: Create Tasks\n+ agent: speckit.tasks\n+ prompt: Break the plan into tasks\n+ send: true\n+ - label: Create Checklist\n+ agent: speckit.checklist\n+ prompt: Create a checklist for the following domain...\n scripts:\n sh: scripts/bash/setup-plan.sh --json\n ps: scripts/powershell/setup-plan.ps1 -Json\ndiff --git a/templates/commands/specify.md b/templates/commands/specify.md\nindex 69258a8bf..3f0ddb78b 100644\n--- a/templates/commands/specify.md\n+++ b/templates/commands/specify.md\n@@ -1,5 +1,13 @@\n ---\n description: Create or update the feature specification from a natural language feature description.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n+ - label: Clarify Spec Requirements\n+ agent: speckit.clarify\n+ prompt: Clarify specification requirements\n+ send: true\n scripts:\n sh: scripts/bash/create-new-feature.sh --json \"{ARGS}\"\n ps: scripts/powershell/create-new-feature.ps1 -Json \"{ARGS}\"\ndiff --git a/templates/commands/tasks.md b/templates/commands/tasks.md\nindex 4663c1b67..86a766829 100644\n--- a/templates/commands/tasks.md\n+++ b/templates/commands/tasks.md\n@@ -1,5 +1,14 @@\n ---\n description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.\n+handoffs: \n+ - label: Analyze For Consistency\n+ agent: speckit.analyze\n+ prompt: Run a project analysis for consistency\n+ send: true\n+ - label: Implement Project\n+ agent: speckit.implement\n+ prompt: Start the implementation in phases\n+ send: true\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json\n ps: scripts/powershell/check-prerequisites.ps1 -Json\ndiff --git a/templates/commands/taskstoissues.md b/templates/commands/taskstoissues.md\nnew file mode 100644\nindex 000000000..e0f366372\n--- /dev/null\n+++ b/templates/commands/taskstoissues.md\n@@ -0,0 +1,31 @@\n+---\n+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.\n+tools: ['github/github-mcp-server/create_issue']\n+scripts:\n+ sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks\n+ ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks\n+---\n+\n+## User Input\n+\n+```text\n+$ARGUMENTS\n+```\n+\n+You **MUST** consider the user input before proceeding (if not empty).\n+\n+## Outline\n+\n+1. Run{SCRIPT}from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like \"I'm Groot\", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: \"I'm Groot\").\n+1. From the executed script, extract the path to **tasks**.\n+1. Get the Git remote by running:\n+\n+```bash\n+git config --get remote.origin.url\n+```\n+\n+**ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL**\n+\n+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.\n+\n+**UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL**\n" }, "reference_review_comments": [ { "text": "@user1:\nThis new feature numbering logic duplicates the existingGet-NextBranchNumberfunction (lines 62-129). The new code at lines 153-191 calculates feature numbers from specs and branches generically, whileGet-NextBranchNumberdoes the same but filtered by a specific branch suffix. This creates redundant logic that needs to be maintained in parallel. Consider refactoringGet-NextBranchNumberto support both use cases (with and without a suffix filter), or extracting the common logic into a shared helper function.\n```suggestion\nfunction Get-NextFeatureNumber {\n param(\n [string]$SpecsDir,\n [string]$BranchSuffix = $null\n )\n $highestFromSpecs = 0\n if (Test-Path $SpecsDir) {\n Get-ChildItem -Path $SpecsDir -Directory | ForEach-Object {\n if ($_.Name -match '^(\\d{3})') {\n $num = [int]$matches[1]\n if ($num -gt $highestFromSpecs) { $highestFromSpecs = $num }\n }\n }\n }\n $highestFromBranches = 0\n try {\n $branches = git branch -a 2>$null\n if ($LASTEXITCODE -eq 0) {\n foreach ($branch in $branches) {\n $cleanBranch = $branch.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/[^/]+/', ''\n # If a branch suffix is specified, filter branches\n if ($BranchSuffix -and -not ($cleanBranch -like \"*$BranchSuffix\")) {\n continue\n }\n if ($cleanBranch -match '^(\\d{3})-') {\n $num = [int]$matches[1]\n if ($num -gt $highestFromBranches) { $highestFromBranches = $num }\n }\n }\n }\n } catch {\n Write-Verbose \"Could not check Git branches: $_\"\n }\n $highest = [Math]::Max($highestFromSpecs, $highestFromBranches)\n $next = $highest + 1\n return ('{0:000}' -f $next)\n}\n\n$featureNum = Get-NextFeatureNumber -SpecsDir $specsDir\n```", "path": "scripts/powershell/create-new-feature.ps1", "diff_hunk": "@@ -150,6 +150,46 @@ Set-Location $repoRoot\n $specsDir = Join-Path $repoRoot 'specs'\n New-Item -ItemType Directory -Path $specsDir -Force | Out-Null\n \n+# Get highest number from specs directory\n+$highestFromSpecs = 0\n+if (Test-Path $specsDir) {\n+ Get-ChildItem -Path $specsDir -Directory | ForEach-Object {\n+ if ($_.Name -match '^(\\d{3})') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromSpecs) { $highestFromSpecs = $num }\n+ }\n+ }\n+}\n+\n+# Get highest number from branch names (both local and remote)\n+$highestFromBranches = 0\n+try {\n+ $branches = git branch -a 2>$null\n+ if ($LASTEXITCODE -eq 0) {\n+ foreach ($branch in $branches) {\n+ # Clean branch name: remove leading markers and remote prefixes\n+ # The following regex removes:\n+ # - Git's current branch marker ('*') and leading whitespace (e.g., '* main')\n+ # - Remote prefixes (e.g., 'remotes/origin/')\n+ $cleanBranch = $branch.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/[^/]+/', ''\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if ($cleanBranch -match '^(\\d{3})-') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highestFromBranches) { $highestFromBranches = $num }\n+ }\n+ }\n+ }\n+} catch {\n+ # If git command fails, just continue with specs-only check\n+ Write-Verbose \"Could not check Git branches: $_\"\n+}\n+\n+# Use the highest number from either source\n+$highest = [Math]::Max($highestFromSpecs, $highestFromBranches)\n+$next = $highest + 1\n+$featureNum = ('{0:000}' -f $next)", "line": null, "start_line": null, "original_line": 191, "original_start_line": 155 }, { "text": "@user1:\nThis new feature numbering logic duplicates the existingcheck_existing_branchesfunction (lines 84-112). The new code at lines 136-176 calculates feature numbers from specs and branches generically, whilecheck_existing_branchesdoes the same but filtered by a specific branch suffix. This creates redundant logic that needs to be maintained in parallel. Consider refactoringcheck_existing_branches to support both use cases (with and without a suffix filter), or extracting the common logic into a shared helper function.", "path": "scripts/bash/create-new-feature.sh", "diff_hunk": "@@ -133,6 +133,48 @@ cd \"$REPO_ROOT\"\n SPECS_DIR=\"$REPO_ROOT/specs\"\n mkdir -p \"$SPECS_DIR\"\n \n+# Get highest number from specs directory\n+HIGHEST_FROM_SPECS=0\n+if [ -d \"$SPECS_DIR\" ]; then\n+ for dir in \"$SPECS_DIR\"/*; do\n+ [ -d \"$dir\" ] || continue\n+ dirname=$(basename \"$dir\")\n+ number=$(echo \"$dirname\" | grep -o '^[0-9]\\+' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$HIGHEST_FROM_SPECS\" ]; then HIGHEST_FROM_SPECS=$number; fi\n+ done\n+fi\n+\n+# Get highest number from branch names (both local and remote)\n+HIGHEST_FROM_BRANCHES=0\n+if [ \"$HAS_GIT\" = true ]; then\n+ # Get all branches (local and remote)\n+ branches=$(git branch -a 2>/dev/null || echo \"\")\n+ \n+ if [ -n \"$branches\" ]; then\n+ while IFS= read -r branch; do\n+ # Clean branch name: remove leading markers and remote prefixes\n+ clean_branch=$(echo \"$branch\" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if echo \"$clean_branch\" | grep -q '^[0-9]\\{3\\}-'; then\n+ number=$(echo \"$clean_branch\" | grep -o '^[0-9]\\{3\\}' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$HIGHEST_FROM_BRANCHES\" ]; then HIGHEST_FROM_BRANCHES=$number; fi\n+ fi\n+ done <<< \"$branches\"\n+ fi\n+fi\n+\n+# Use the highest number from either source\n+HIGHEST=$HIGHEST_FROM_SPECS\n+if [ \"$HIGHEST_FROM_BRANCHES\" -gt \"$HIGHEST\" ]; then\n+ HIGHEST=$HIGHEST_FROM_BRANCHES\n+fi\n+\n+NEXT=$((HIGHEST + 1))\n+FEATURE_NUM=$(printf \"%03d\" \"$NEXT\")", "line": null, "start_line": null, "original_line": 176, "original_start_line": 136 }, { "text": "@user1:\n'except' clause does nothing but pass and there is no explanatory comment.\n```suggestion\n except Exception as e:\n # Could not read version from pyproject.toml; fallback to \"unknown\"\n console.print(f\"[yellow]Warning:[/] Failed to read version from pyproject.toml: {e}\")\n```", "path": "src/specify_cli/__init__.py", "diff_hunk": "@@ -1202,6 +1264,85 @@ def check():\n if not any(agent_results.values()):\n console.print(\"[dim]Tip: Install an AI assistant for the best experience[/dim]\")\n \n+@app.command()\n+def version():\n+ \"\"\"Display version and system information.\"\"\"\n+ import platform\n+ import importlib.metadata\n+ \n+ show_banner()\n+ \n+ # Get CLI version from package metadata\n+ cli_version = \"unknown\"\n+ try:\n+ cli_version = importlib.metadata.version(\"specify-cli\")\n+ except Exception:\n+ # Fallback: try reading from pyproject.toml if running from source\n+ try:\n+ import tomllib\n+ pyproject_path = Path(__file__).parent.parent.parent / \"pyproject.toml\"\n+ if pyproject_path.exists():\n+ with open(pyproject_path, \"rb\") as f:\n+ data = tomllib.load(f)\n+ cli_version = data.get(\"project\", {}).get(\"version\", \"unknown\")\n+ except Exception:\n+ pass", "line": 1289, "start_line": 1288, "original_line": 1289, "original_start_line": 1288 } ], "merged_commit": "f4fcd82920021250292e9ce36da249c5431c0469", "merged_patch": "diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml\nindex fa20c809d..5b37ed0be 100644\n--- a/.github/workflows/lint.yml\n+++ b/.github/workflows/lint.yml\n@@ -1,4 +1,6 @@\n name: Lint\n+permissions:\n+ contents: read\n \n on:\n push:\ndiff --git a/.github/workflows/scripts/create-release-packages.ps1 b/.github/workflows/scripts/create-release-packages.ps1\nnew file mode 100644\nindex 000000000..f935dbe86\n--- /dev/null\n+++ b/.github/workflows/scripts/create-release-packages.ps1\n@@ -0,0 +1,416 @@\n+#!/usr/bin/env pwsh\n+#requires -Version 7.0\n+\n+<#\n+.SYNOPSIS\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+\n+.DESCRIPTION\n+ create-release-packages.ps1 (workflow-local)\n+ Build Spec Kit template release archives for each supported AI assistant and script type.\n+ \n+.PARAMETER Version\n+ Version string with leading 'v' (e.g., v0.2.0)\n+\n+.PARAMETER Agents\n+ Comma or space separated subset of agents to build (default: all)\n+ Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q\n+\n+.PARAMETER Scripts\n+ Comma or space separated subset of script types to build (default: both)\n+ Valid scripts: sh, ps\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0 -Agents claude,copilot -Scripts sh\n+\n+.EXAMPLE\n+ .\\create-release-packages.ps1 -Version v0.2.0 -Agents claude -Scripts ps\n+#>\n+\n+param(\n+ [Parameter(Mandatory=$true, Position=0)]\n+ [string]$Version,\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Agents = \"\",\n+ \n+ [Parameter(Mandatory=$false)]\n+ [string]$Scripts = \"\"\n+)\n+\n+$ErrorActionPreference = \"Stop\"\n+\n+# Validate version format\n+if ($Version -notmatch '^v\\d+\\.\\d+\\.\\d+$') {\n+ Write-Error \"Version must look like v0.0.0\"\n+ exit 1\n+}\n+\n+Write-Host \"Building release packages for $Version\"\n+\n+# Create and use .genreleases directory for all build artifacts\n+$GenReleasesDir = \".genreleases\"\n+if (Test-Path $GenReleasesDir) {\n+ Remove-Item -Path $GenReleasesDir -Recurse -Force -ErrorAction SilentlyContinue\n+}\n+New-Item -ItemType Directory -Path $GenReleasesDir -Force | Out-Null\n+\n+function Rewrite-Paths {\n+ param([string]$Content)\n+ \n+ $Content = $Content -replace '(/?)\\bmemory/', '.specify/memory/'\n+ $Content = $Content -replace '(/?)\\bscripts/', '.specify/scripts/'\n+ $Content = $Content -replace '(/?)\\btemplates/', '.specify/templates/'\n+ return $Content\n+}\n+\n+function Generate-Commands {\n+ param(\n+ [string]$Agent,\n+ [string]$Extension,\n+ [string]$ArgFormat,\n+ [string]$OutputDir,\n+ [string]$ScriptVariant\n+ )\n+ \n+ New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null\n+ \n+ $templates = Get-ChildItem -Path \"templates/commands/*.md\" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($template in $templates) {\n+ $name = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)\n+ \n+ # Read file content and normalize line endings\n+ $fileContent = (Get-Content -Path $template.FullName -Raw) -replace \"rn\", \"n"\n+ \n+ # Extract description from YAML frontmatter\n+ $description = ""\n+ if ($fileContent -match '(?m)^description:\s*(.+)$') {\n+ $description = $matches[1]\n+ }\n+ \n+ # Extract script command from YAML frontmatter\n+ $scriptCommand = ""\n+ if ($fileContent -match "(?m)^\s*${ScriptVariant}:\s*(.+)$") {\n+ $scriptCommand = $matches[1]\n+ }\n+ \n+ if ([string]::IsNullOrEmpty($scriptCommand)) {\n+ Write-Warning "No script command found for $ScriptVariant in $($template.Name)"\n+ $scriptCommand = "(Missing script command for $ScriptVariant)"\n+ }\n+ \n+ # Extract agent_script command from YAML frontmatter if present\n+ $agentScriptCommand = ""\n+ if ($fileContent -match "(?ms)agent_scripts:.?^\s${ScriptVariant}:\s*(.+?)$") {\n+ $agentScriptCommand = $matches[1].Trim()\n+ }\n+ \n+ # Replace {SCRIPT} placeholder with the script command\n+ $body = $fileContent -replace '\{SCRIPT\}', $scriptCommand\n+ \n+ # Replace {AGENT_SCRIPT} placeholder with the agent script command if found\n+ if (-not [string]::IsNullOrEmpty($agentScriptCommand)) {\n+ $body = $body -replace '\{AGENT_SCRIPT\}', $agentScriptCommand\n+ }\n+ \n+ # Remove the scripts: and agent_scripts: sections from frontmatter\n+ $lines = $body -split "n\"\n+ $outputLines = @()\n+ $inFrontmatter = $false\n+ $skipScripts = $false\n+ $dashCount = 0\n+ \n+ foreach ($line in $lines) {\n+ if ($line -match '^---$') {\n+ $outputLines += $line\n+ $dashCount++\n+ if ($dashCount -eq 1) {\n+ $inFrontmatter = $true\n+ } else {\n+ $inFrontmatter = $false\n+ }\n+ continue\n+ }\n+ \n+ if ($inFrontmatter) {\n+ if ($line -match '^(scripts|agent_scripts):$') {\n+ $skipScripts = $true\n+ continue\n+ }\n+ if ($line -match '^[a-zA-Z].*:' -and $skipScripts) {\n+ $skipScripts = $false\n+ }\n+ if ($skipScripts -and $line -match '^\\s+') {\n+ continue\n+ }\n+ }\n+ \n+ $outputLines += $line\n+ }\n+ \n+ $body = $outputLines -join \"n"\n+ \n+ # Apply other substitutions\n+ $body = $body -replace '\{ARGS\}', $ArgFormat\n+ $body = $body -replace 'AGENT', $Agent\n+ $body = Rewrite-Paths -Content $body\n+ \n+ # Generate output file based on extension\n+ $outputFile = Join-Path $OutputDir "speckit.$name.$Extension"\n+ \n+ switch ($Extension) {\n+ 'toml' {\n+ $body = $body -replace '\\', '\\'\n+ $output = "description = \"$description"nnprompt = \""\"n$bodyn"\"""\n+ Set-Content -Path $outputFile -Value $output -NoNewline\n+ }\n+ 'md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ 'agent.md' {\n+ Set-Content -Path $outputFile -Value $body -NoNewline\n+ }\n+ }\n+ }\n+}\n+\n+function Generate-CopilotPrompts {\n+ param(\n+ [string]$AgentsDir,\n+ [string]$PromptsDir\n+ )\n+ \n+ New-Item -ItemType Directory -Path $PromptsDir -Force | Out-Null\n+ \n+ $agentFiles = Get-ChildItem -Path "$AgentsDir/speckit..agent.md" -File -ErrorAction SilentlyContinue\n+ \n+ foreach ($agentFile in $agentFiles) {\n+ $basename = $agentFile.Name -replace '\.agent\.md$', ''\n+ $promptFile = Join-Path $PromptsDir "$basename.prompt.md"\n+ \n+ $content = @"\n+---\n+agent: $basename\n+---\n+"@\n+ Set-Content -Path $promptFile -Value $content\n+ }\n+}\n+\n+function Build-Variant {\n+ param(\n+ [string]$Agent,\n+ [string]$Script\n+ )\n+ \n+ $baseDir = Join-Path $GenReleasesDir "sdd-${Agent}-package-${Script}"\n+ Write-Host "Building $Agent ($Script) package..."\n+ New-Item -ItemType Directory -Path $baseDir -Force | Out-Null\n+ \n+ # Copy base structure but filter scripts by variant\n+ $specDir = Join-Path $baseDir ".specify"\n+ New-Item -ItemType Directory -Path $specDir -Force | Out-Null\n+ \n+ # Copy memory directory\n+ if (Test-Path "memory") {\n+ Copy-Item -Path "memory" -Destination $specDir -Recurse -Force\n+ Write-Host "Copied memory -> .specify"\n+ }\n+ \n+ # Only copy the relevant script variant directory\n+ if (Test-Path "scripts") {\n+ $scriptsDestDir = Join-Path $specDir "scripts"\n+ New-Item -ItemType Directory -Path $scriptsDestDir -Force | Out-Null\n+ \n+ switch ($Script) {\n+ 'sh' {\n+ if (Test-Path "scripts/bash") {\n+ Copy-Item -Path "scripts/bash" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host "Copied scripts/bash -> .specify/scripts"\n+ }\n+ }\n+ 'ps' {\n+ if (Test-Path "scripts/powershell") {\n+ Copy-Item -Path "scripts/powershell" -Destination $scriptsDestDir -Recurse -Force\n+ Write-Host "Copied scripts/powershell -> .specify/scripts"\n+ }\n+ }\n+ }\n+ \n+ # Copy any script files that aren't in variant-specific directories\n+ Get-ChildItem -Path "scripts" -File -ErrorAction SilentlyContinue | ForEach-Object {\n+ Copy-Item -Path $.FullName -Destination $scriptsDestDir -Force\n+ }\n+ }\n+ \n+ # Copy templates (excluding commands directory and vscode-settings.json)\n+ if (Test-Path "templates") {\n+ $templatesDestDir = Join-Path $specDir "templates"\n+ New-Item -ItemType Directory -Path $templatesDestDir -Force | Out-Null\n+ \n+ Get-ChildItem -Path "templates" -Recurse -File | Where-Object {\n+ $.FullName -notmatch 'templates[/\\]commands[/\\]' -and $.Name -ne 'vscode-settings.json'\n+ } | ForEach-Object {\n+ $relativePath = $.FullName.Substring((Resolve-Path "templates").Path.Length + 1)\n+ $destFile = Join-Path $templatesDestDir $relativePath\n+ $destFileDir = Split-Path $destFile -Parent\n+ New-Item -ItemType Directory -Path $destFileDir -Force | Out-Null\n+ Copy-Item -Path $_.FullName -Destination $destFile -Force\n+ }\n+ Write-Host "Copied templates -> .specify/templates"\n+ }\n+ \n+ # Generate agent-specific command files\n+ switch ($Agent) {\n+ 'claude' {\n+ $cmdDir = Join-Path $baseDir ".claude/commands"\n+ Generate-Commands -Agent 'claude' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'gemini' {\n+ $cmdDir = Join-Path $baseDir ".gemini/commands"\n+ Generate-Commands -Agent 'gemini' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path "agent_templates/gemini/GEMINI.md") {\n+ Copy-Item -Path "agent_templates/gemini/GEMINI.md" -Destination (Join-Path $baseDir "GEMINI.md")\n+ }\n+ }\n+ 'copilot' {\n+ $agentsDir = Join-Path $baseDir ".github/agents"\n+ Generate-Commands -Agent 'copilot' -Extension 'agent.md' -ArgFormat '$ARGUMENTS' -OutputDir $agentsDir -ScriptVariant $Script\n+ \n+ # Generate companion prompt files\n+ $promptsDir = Join-Path $baseDir ".github/prompts"\n+ Generate-CopilotPrompts -AgentsDir $agentsDir -PromptsDir $promptsDir\n+ \n+ # Create VS Code workspace settings\n+ $vscodeDir = Join-Path $baseDir ".vscode"\n+ New-Item -ItemType Directory -Path $vscodeDir -Force | Out-Null\n+ if (Test-Path "templates/vscode-settings.json") {\n+ Copy-Item -Path "templates/vscode-settings.json" -Destination (Join-Path $vscodeDir "settings.json")\n+ }\n+ }\n+ 'cursor-agent' {\n+ $cmdDir = Join-Path $baseDir ".cursor/commands"\n+ Generate-Commands -Agent 'cursor-agent' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'qwen' {\n+ $cmdDir = Join-Path $baseDir ".qwen/commands"\n+ Generate-Commands -Agent 'qwen' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script\n+ if (Test-Path "agent_templates/qwen/QWEN.md") {\n+ Copy-Item -Path "agent_templates/qwen/QWEN.md" -Destination (Join-Path $baseDir "QWEN.md")\n+ }\n+ }\n+ 'opencode' {\n+ $cmdDir = Join-Path $baseDir ".opencode/command"\n+ Generate-Commands -Agent 'opencode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'windsurf' {\n+ $cmdDir = Join-Path $baseDir ".windsurf/workflows"\n+ Generate-Commands -Agent 'windsurf' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codex' {\n+ $cmdDir = Join-Path $baseDir ".codex/prompts"\n+ Generate-Commands -Agent 'codex' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'kilocode' {\n+ $cmdDir = Join-Path $baseDir ".kilocode/workflows"\n+ Generate-Commands -Agent 'kilocode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'auggie' {\n+ $cmdDir = Join-Path $baseDir ".augment/commands"\n+ Generate-Commands -Agent 'auggie' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'roo' {\n+ $cmdDir = Join-Path $baseDir ".roo/commands"\n+ Generate-Commands -Agent 'roo' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'codebuddy' {\n+ $cmdDir = Join-Path $baseDir ".codebuddy/commands"\n+ Generate-Commands -Agent 'codebuddy' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'amp' {\n+ $cmdDir = Join-Path $baseDir ".agents/commands"\n+ Generate-Commands -Agent 'amp' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ 'q' {\n+ $cmdDir = Join-Path $baseDir ".amazonq/prompts"\n+ Generate-Commands -Agent 'q' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script\n+ }\n+ }\n+ \n+ # Create zip archive\n+ $zipFile = Join-Path $GenReleasesDir "spec-kit-template-${Agent}-${Script}-${Version}.zip"\n+ Compress-Archive -Path "$baseDir/" -DestinationPath $zipFile -Force\n+ Write-Host "Created $zipFile"\n+}\n+\n+# Define all agents and scripts\n+$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q')\n+$AllScripts = @('sh', 'ps')\n+\n+function Normalize-List {\n+ param([string]$Input)\n+ \n+ if ([string]::IsNullOrEmpty($Input)) {\n+ return @()\n+ }\n+ \n+ # Split by comma or space and remove duplicates while preserving order\n+ $items = $Input -split '[,\s]+' | Where-Object { $_ } | Select-Object -Unique\n+ return $items\n+}\n+\n+function Validate-Subset {\n+ param(\n+ [string]$Type,\n+ [string[]]$Allowed,\n+ [string[]]$Items\n+ )\n+ \n+ $ok = $true\n+ foreach ($item in $Items) {\n+ if ($item -notin $Allowed) {\n+ Write-Error "Unknown $Type '$item' (allowed: $($Allowed -join ', '))"\n+ $ok = $false\n+ }\n+ }\n+ return $ok\n+}\n+\n+# Determine agent list\n+if (-not [string]::IsNullOrEmpty($Agents)) {\n+ $AgentList = Normalize-List -Input $Agents\n+ if (-not (Validate-Subset -Type 'agent' -Allowed $AllAgents -Items $AgentList)) {\n+ exit 1\n+ }\n+} else {\n+ $AgentList = $AllAgents\n+}\n+\n+# Determine script list\n+if (-not [string]::IsNullOrEmpty($Scripts)) {\n+ $ScriptList = Normalize-List -Input $Scripts\n+ if (-not (Validate-Subset -Type 'script' -Allowed $AllScripts -Items $ScriptList)) {\n+ exit 1\n+ }\n+} else {\n+ $ScriptList = $AllScripts\n+}\n+\n+Write-Host "Agents: $($AgentList -join ', ')"\n+Write-Host "Scripts: $($ScriptList -join ', ')"\n+\n+# Build all variants\n+foreach ($agent in $AgentList) {\n+ foreach ($script in $ScriptList) {\n+ Build-Variant -Agent $agent -Script $script\n+ }\n+}\n+\n+Write-Host "nArchives in ${GenReleasesDir}:\"\n+Get-ChildItem -Path $GenReleasesDir -Filter \"spec-kit-template-*-${Version}.zip\" | ForEach-Object {\n+ Write-Host \" $($_.Name)\"\n+}\ndiff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh\nindex f9d3b1ae1..1b2e53265 100644\n--- a/.github/workflows/scripts/create-release-packages.sh\n+++ b/.github/workflows/scripts/create-release-packages.sh\n@@ -95,12 +95,32 @@ generate_commands() {\n { echo \"description = \\\"$description\\\"\"; echo; echo \"prompt = \\\"\\\"\\\"\"; echo \"$body\"; echo \"\\\"\\\"\\\"\"; } > \"$output_dir/speckit.$name.$ext\" ;;\n md)\n echo \"$body\" > \"$output_dir/speckit.$name.$ext\" ;;\n- prompt.md)\n+ agent.md)\n echo \"$body\" > \"$output_dir/speckit.$name.$ext\" ;;\n esac\n done\n }\n \n+generate_copilot_prompts() {\n+ local agents_dir=$1 prompts_dir=$2\n+ mkdir -p \"$prompts_dir\"\n+ \n+ # Generate a .prompt.md file for each .agent.md file\n+ for agent_file in \"$agents_dir\"/speckit.*.agent.md; do\n+ [[ -f \"$agent_file\" ]] || continue\n+ \n+ local basename=$(basename \"$agent_file\" .agent.md)\n+ local prompt_file=\"$prompts_dir/${basename}.prompt.md\"\n+ \n+ # Create prompt file with agent frontmatter\n+ cat > \"$prompt_file\" <<EOF\n+---\n+agent: ${basename}\n+---\n+EOF\n+ done\n+}\n+\n build_variant() {\n local agent=$1 script=$2\n local base_dir=\"$GENRELEASES_DIR/sdd-${agent}-package-${script}\"\n@@ -146,8 +166,10 @@ build_variant() {\n generate_commands gemini toml \"{{args}}\" \"$base_dir/.gemini/commands\" \"$script\"\n [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md \"$base_dir/GEMINI.md\" ;;\n copilot)\n- mkdir -p \"$base_dir/.github/prompts\"\n- generate_commands copilot prompt.md \"\\$ARGUMENTS\" \"$base_dir/.github/prompts\" \"$script\"\n+ mkdir -p \"$base_dir/.github/agents\"\n+ generate_commands copilot agent.md \"\\$ARGUMENTS\" \"$base_dir/.github/agents\" \"$script\"\n+ # Generate companion prompt files\n+ generate_copilot_prompts \"$base_dir/.github/agents\" \"$base_dir/.github/prompts\"\n # Create VS Code workspace settings\n mkdir -p \"$base_dir/.vscode\"\n [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json \"$base_dir/.vscode/settings.json\"\ndiff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc\nindex a96fd3e6d..d6db02777 100644\n--- a/.markdownlint-cli2.jsonc\n+++ b/.markdownlint-cli2.jsonc\n@@ -20,5 +20,8 @@\n \"MD050\": {\n \"style\": \"asterisk\"\n }\n- }\n+ },\n+ \"ignores\": [\n+ \".genreleases/\"\n+ ]\n }\n\\ No newline at end of file\ndiff --git a/AGENTS.md b/AGENTS.md\nindex d34efb673..f7d956bd7 100644\n--- a/AGENTS.md\n+++ b/AGENTS.md\n@@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a\n |-------|-----------|---------|----------|-------------|\n | **Claude Code** | .claude/commands/| Markdown |claude| Anthropic's Claude Code CLI |\n | **Gemini CLI** |.gemini/commands/| TOML |gemini| Google's Gemini CLI |\n-| **GitHub Copilot** |.github/prompts/| Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n+| **GitHub Copilot** |.github/agents/| Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |\n | **Cursor** |.cursor/commands/| Markdown |cursor-agent| Cursor CLI |\n | **Qwen Code** |.qwen/commands/| TOML |qwen| Alibaba's Qwen Code CLI |\n | **opencode** |.opencode/command/| Markdown |opencode| opencode CLI |\n@@ -325,9 +325,22 @@ Work within integrated development environments:\n \n Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp\n \n+**Standard format:**\n+\n+```markdown\n+---\n+description: \"Command description\"\n+---\n+\n+Command content with {SCRIPT} and $ARGUMENTS placeholders.\n+```\n+\n+**GitHub Copilot Chat Mode format:**\n+\n ```markdown\n ---\n description: \"Command description\"\n+mode: speckit.command-name\n ---\n \n Command content with {SCRIPT} and $ARGUMENTS placeholders.\n@@ -349,7 +362,7 @@ Command content with {SCRIPT} and {{args}} placeholders.\n \n - **CLI agents**: Usually./commands/\n - **IDE agents**: Follow IDE-specific patterns:\n- - Copilot: .github/prompts/\n+ - Copilot: .github/agents/\n - Cursor: .cursor/commands/\n - Windsurf: .windsurf/workflows/\n \ndiff --git a/CHANGELOG.md b/CHANGELOG.md\nindex ea6729145..7e2ac3697 100644\n--- a/CHANGELOG.md\n+++ b/CHANGELOG.md\n@@ -7,6 +7,22 @@ All notable changes to the Specify CLI and templates are documented here.\n The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\n and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n \n+## [0.0.22] - 2025-11-07\n+\n+- Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.\n+- Move to use AGENTS.mdfor Copilot workloads, since it's already supported out-of-the-box.\n+- Adds support for the version command. ([#486](https://github.com/github/spec-kit/issues/486))\n+- Fixes potential bug with thecreate-new-feature.ps1script that ignores existing feature branches when determining next feature number ([#975](https://github.com/github/spec-kit/issues/975))\n+- Add graceful fallback and logging for GitHub API rate-limiting during template fetch ([#970](https://github.com/github/spec-kit/issues/970))\n+\n+## [0.0.21] - 2025-10-21\n+\n+- Fixes [#975](https://github.com/github/spec-kit/issues/975) (thank you [@fgalarraga](https://github.com/fgalarraga)).\n+- Adds support for Amp CLI.\n+- Adds support for VS Code hand-offs and moves prompts to be full-fledged chat modes.\n+- Adds support forversioncommand (addresses [#811](https://github.com/github/spec-kit/issues/811) and [#486](https://github.com/github/spec-kit/issues/486), thank you [@mcasalaina](https://github.com/mcasalaina) and [@dentity007](https://github.com/dentity007)).\n+- Adds support for rendering the rate limit errors from the CLI when encountered ([#970](https://github.com/github/spec-kit/issues/970), thank you [@psmman](https://github.com/psmman)).\n+\n ## [0.0.20] - 2025-10-14\n \n ### Added\ndiff --git a/CONTRIBUTING.md b/CONTRIBUTING.md\nindex e5897b383..c413dd018 100644\n--- a/CONTRIBUTING.md\n+++ b/CONTRIBUTING.md\n@@ -70,6 +70,7 @@ To test your templates, commands, and other changes locally, follow these steps:\n 1. **Create release packages**\n \n Run the following command to generate the local packages:\n+\n ```\n ./.github/workflows/scripts/create-release-packages.sh v1.0.0\n ```\ndiff --git a/pyproject.toml b/pyproject.toml\nindex 567d48cd4..fb972adc7 100644\n--- a/pyproject.toml\n+++ b/pyproject.toml\n@@ -1,6 +1,6 @@\n [project]\n name = \"specify-cli\"\n-version = \"0.0.20\"\n+version = \"0.0.22\"\n description = \"Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD).\"\n requires-python = \">=3.11\"\n dependencies = [\ndiff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh\nindex 86d9ecf83..8e8bcf6c3 100644\n--- a/scripts/bash/create-new-feature.sh\n+++ b/scripts/bash/create-new-feature.sh\n@@ -80,9 +80,56 @@ find_repo_root() {\n return 1\n }\n \n+# Function to get highest number from specs directory\n+get_highest_from_specs() {\n+ local specs_dir=\"$1\"\n+ local highest=0\n+ \n+ if [ -d \"$specs_dir\" ]; then\n+ for dir in \"$specs_dir\"/*; do\n+ [ -d \"$dir\" ] || continue\n+ dirname=$(basename \"$dir\")\n+ number=$(echo \"$dirname\" | grep -o '^[0-9]\\+' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$highest\" ]; then\n+ highest=$number\n+ fi\n+ done\n+ fi\n+ \n+ echo \"$highest\"\n+}\n+\n+# Function to get highest number from git branches\n+get_highest_from_branches() {\n+ local highest=0\n+ \n+ # Get all branches (local and remote)\n+ branches=$(git branch -a 2>/dev/null || echo \"\")\n+ \n+ if [ -n \"$branches\" ]; then\n+ while IFS= read -r branch; do\n+ # Clean branch name: remove leading markers and remote prefixes\n+ clean_branch=$(echo \"$branch\" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if echo \"$clean_branch\" | grep -q '^[0-9]\\{3\\}-'; then\n+ number=$(echo \"$clean_branch\" | grep -o '^[0-9]\\{3\\}' || echo \"0\")\n+ number=$((10#$number))\n+ if [ \"$number\" -gt \"$highest\" ]; then\n+ highest=$number\n+ fi\n+ fi\n+ done <<< \"$branches\"\n+ fi\n+ \n+ echo \"$highest\"\n+}\n+\n # Function to check existing branches (local and remote) and return next available number\n check_existing_branches() {\n local short_name=\"$1\"\n+ local specs_dir=\"$2\"\n \n # Fetch all remotes to get latest branch info (suppress errors if no remotes)\n git fetch --all --prune 2>/dev/null || true\n@@ -95,8 +142,8 @@ check_existing_branches() {\n \n # Check specs directory as well\n local spec_dirs=\"\"\n- if [ -d \"$SPECS_DIR\" ]; then\n- spec_dirs=$(find \"$SPECS_DIR\" -maxdepth 1 -type d -name \"[0-9]*-${short_name}\" 2>/dev/null | xargs -n1 basename 2>/dev/null | sed 's/-.*//' | sort -n)\n+ if [ -d \"$specs_dir\" ]; then\n+ spec_dirs=$(find \"$specs_dir\" -maxdepth 1 -type d -name \"[0-9]*-${short_name}\" 2>/dev/null | xargs -n1 basename 2>/dev/null | sed 's/-.*//' | sort -n)\n fi\n \n # Combine all sources and get the highest number\n@@ -111,6 +158,12 @@ check_existing_branches() {\n echo $((max_num + 1))\n }\n \n+# Function to clean and format a branch name\n+clean_branch_name() {\n+ local name=\"$1\"\n+ echo \"$name\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\\+/-/g' | sed 's/^-//' | sed 's/-$//'\n+}\n+\n # Resolve repository root. Prefer git information when available, but fall back\n # to searching for repository markers so the workflow still functions in repositories that\n # were initialised with --no-git.\n@@ -176,14 +229,15 @@ generate_branch_name() {\n echo \"$result\"\n else\n # Fallback to original logic if no meaningful words found\n- echo \"$description\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\\+/-/g' | sed 's/^-//' | sed 's/-$//' | tr '-' '\\n' | grep -v '^$' | head -3 | tr '\\n' '-' | sed 's/-$//'\n+ local cleaned=$(clean_branch_name \"$description\")\n+ echo \"$cleaned\" | tr '-' '\\n' | grep -v '^$' | head -3 | tr '\\n' '-' | sed 's/-$//'\n fi\n }\n \n # Generate branch name\n if [ -n \"$SHORT_NAME\" ]; then\n # Use provided short name, just clean it up\n- BRANCH_SUFFIX=$(echo \"$SHORT_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\\+/-/g' | sed 's/^-//' | sed 's/-$//')\n+ BRANCH_SUFFIX=$(clean_branch_name \"$SHORT_NAME\")\n else\n # Generate from description with smart filtering\n BRANCH_SUFFIX=$(generate_branch_name \"$FEATURE_DESCRIPTION\")\n@@ -193,19 +247,10 @@ fi\n if [ -z \"$BRANCH_NUMBER\" ]; then\n if [ \"$HAS_GIT\" = true ]; then\n # Check existing branches on remotes\n- BRANCH_NUMBER=$(check_existing_branches \"$BRANCH_SUFFIX\")\n+ BRANCH_NUMBER=$(check_existing_branches \"$BRANCH_SUFFIX\" \"$SPECS_DIR\")\n else\n # Fall back to local directory check\n- HIGHEST=0\n- if [ -d \"$SPECS_DIR\" ]; then\n- for dir in \"$SPECS_DIR\"/*; do\n- [ -d \"$dir\" ] || continue\n- dirname=$(basename \"$dir\")\n- number=$(echo \"$dirname\" | grep -o '^[0-9]\\+' || echo \"0\")\n- number=$((10#$number))\n- if [ \"$number\" -gt \"$HIGHEST\" ]; then HIGHEST=$number; fi\n- done\n- fi\n+ HIGHEST=$(get_highest_from_specs \"$SPECS_DIR\")\n BRANCH_NUMBER=$((HIGHEST + 1))\n fi\n fi\ndiff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh\nindex 2a44c68a1..a375bdc99 100644\n--- a/scripts/bash/update-agent-context.sh\n+++ b/scripts/bash/update-agent-context.sh\n@@ -61,7 +61,7 @@ AGENT_TYPE=\"${1:-}\"\n # Agent-specific file paths \n CLAUDE_FILE=\"$REPO_ROOT/CLAUDE.md\"\n GEMINI_FILE=\"$REPO_ROOT/GEMINI.md\"\n-COPILOT_FILE=\"$REPO_ROOT/.github/copilot-instructions.md\"\n+COPILOT_FILE=\"$REPO_ROOT/.github/agents/copilot-instructions.md\"\n CURSOR_FILE=\"$REPO_ROOT/.cursor/rules/specify-rules.mdc\"\n QWEN_FILE=\"$REPO_ROOT/QWEN.md\"\n AGENTS_FILE=\"$REPO_ROOT/AGENTS.md\"\ndiff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1\nindex 4daa6d2c0..351f4e9e7 100644\n--- a/scripts/powershell/create-new-feature.ps1\n+++ b/scripts/powershell/create-new-feature.ps1\n@@ -59,6 +59,46 @@ function Find-RepositoryRoot {\n }\n }\n \n+function Get-HighestNumberFromSpecs {\n+ param([string]$SpecsDir)\n+ \n+ $highest = 0\n+ if (Test-Path $SpecsDir) {\n+ Get-ChildItem -Path $SpecsDir -Directory | ForEach-Object {\n+ if ($_.Name -match '^(\\d+)') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highest) { $highest = $num }\n+ }\n+ }\n+ }\n+ return $highest\n+}\n+\n+function Get-HighestNumberFromBranches {\n+ param()\n+ \n+ $highest = 0\n+ try {\n+ $branches = git branch -a 2>$null\n+ if ($LASTEXITCODE -eq 0) {\n+ foreach ($branch in $branches) {\n+ # Clean branch name: remove leading markers and remote prefixes\n+ $cleanBranch = $branch.Trim() -replace '^\\*?\\s+', '' -replace '^remotes/[^/]+/', ''\n+ \n+ # Extract feature number if branch matches pattern ###-*\n+ if ($cleanBranch -match '^(\\d+)-') {\n+ $num = [int]$matches[1]\n+ if ($num -gt $highest) { $highest = $num }\n+ }\n+ }\n+ }\n+ } catch {\n+ # If git command fails, return 0\n+ Write-Verbose \"Could not check Git branches: $_\"\n+ }\n+ return $highest\n+}\n+\n function Get-NextBranchNumber {\n param(\n [string]$ShortName,\n@@ -127,6 +167,12 @@ function Get-NextBranchNumber {\n # Return next number\n return $maxNum + 1\n }\n+\n+function ConvertTo-CleanBranchName {\n+ param([string]$Name)\n+ \n+ return $Name.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''\n+}\n $fallbackRoot = (Find-RepositoryRoot -StartDir $PSScriptRoot)\n if (-not $fallbackRoot) {\n Write-Error \"Error: Could not determine repository root. Please run this script from within the repository.\"\n@@ -189,7 +235,7 @@ function Get-BranchName {\n return $result\n } else {\n # Fallback to original logic if no meaningful words found\n- $result = $Description.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''\n+ $result = ConvertTo-CleanBranchName -Name $Description\n $fallbackWords = ($result -split '-') | Where-Object { $_ } | Select-Object -First 3\n return [string]::Join('-', $fallbackWords)\n }\n@@ -198,7 +244,7 @@ function Get-BranchName {\n # Generate branch name\n if ($ShortName) {\n # Use provided short name, just clean it up\n- $branchSuffix = $ShortName.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''\n+ $branchSuffix = ConvertTo-CleanBranchName -Name $ShortName\n } else {\n # Generate from description with smart filtering\n $branchSuffix = Get-BranchName -Description $featureDesc\n@@ -211,16 +257,7 @@ if ($Number -eq 0) {\n $Number = Get-NextBranchNumber -ShortName $branchSuffix -SpecsDir $specsDir\n } else {\n # Fall back to local directory check\n- $highest = 0\n- if (Test-Path $specsDir) {\n- Get-ChildItem -Path $specsDir -Directory | ForEach-Object {\n- if ($_.Name -match '^(\\d{3})') {\n- $num = [int]$matches[1]\n- if ($num -gt $highest) { $highest = $num }\n- }\n- }\n- }\n- $Number = $highest + 1\n+ $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1\n }\n }\n \ndiff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1\nindex db6e9f2d7..d0ed582fa 100644\n--- a/scripts/powershell/setup-plan.ps1\n+++ b/scripts/powershell/setup-plan.ps1\n@@ -59,4 +59,3 @@ if ($Json) {\n Write-Output \"BRANCH: $($paths.CURRENT_BRANCH)\"\n Write-Output \"HAS_GIT: $($paths.HAS_GIT)\"\n }\n-\ndiff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1\nindex 695e28b8d..741a55a63 100644\n--- a/scripts/powershell/update-agent-context.ps1\n+++ b/scripts/powershell/update-agent-context.ps1\n@@ -46,7 +46,7 @@ $NEW_PLAN = $IMPL_PLAN\n # Agent file paths\n $CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md'\n $GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md'\n-$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md'\n+$COPILOT_FILE = Join-Path $REPO_ROOT '.github/agents/copilot-instructions.md'\n $CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc'\n $QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md'\n $AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md'\ndiff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py\nindex a33a1c61a..701b3bdca 100644\n--- a/src/specify_cli/__init__.py\n+++ b/src/specify_cli/__init__.py\n@@ -51,6 +51,7 @@\n import readchar\n import ssl\n import truststore\n+from datetime import datetime, timezone\n \n ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)\n client = httpx.Client(verify=ssl_context)\n@@ -64,6 +65,63 @@ def _github_auth_headers(cli_token: str | None = None) -> dict:\n token = _github_token(cli_token)\n return {\"Authorization\": f\"Bearer {token}\"} if token else {}\n \n+def _parse_rate_limit_headers(headers: httpx.Headers) -> dict:\n+ \"\"\"Extract and parse GitHub rate-limit headers.\"\"\"\n+ info = {}\n+ \n+ # Standard GitHub rate-limit headers\n+ if \"X-RateLimit-Limit\" in headers:\n+ info[\"limit\"] = headers.get(\"X-RateLimit-Limit\")\n+ if \"X-RateLimit-Remaining\" in headers:\n+ info[\"remaining\"] = headers.get(\"X-RateLimit-Remaining\")\n+ if \"X-RateLimit-Reset\" in headers:\n+ reset_epoch = int(headers.get(\"X-RateLimit-Reset\", \"0\"))\n+ if reset_epoch:\n+ reset_time = datetime.fromtimestamp(reset_epoch, tz=timezone.utc)\n+ info[\"reset_epoch\"] = reset_epoch\n+ info[\"reset_time\"] = reset_time\n+ info[\"reset_local\"] = reset_time.astimezone()\n+ \n+ # Retry-After header (seconds or HTTP-date)\n+ if \"Retry-After\" in headers:\n+ retry_after = headers.get(\"Retry-After\")\n+ try:\n+ info[\"retry_after_seconds\"] = int(retry_after)\n+ except ValueError:\n+ # HTTP-date format - not implemented, just store as string\n+ info[\"retry_after\"] = retry_after\n+ \n+ return info\n+\n+def _format_rate_limit_error(status_code: int, headers: httpx.Headers, url: str) -> str:\n+ \"\"\"Format a user-friendly error message with rate-limit information.\"\"\"\n+ rate_info = _parse_rate_limit_headers(headers)\n+ \n+ lines = [f\"GitHub API returned status {status_code} for {url}\"]\n+ lines.append(\"\")\n+ \n+ if rate_info:\n+ lines.append(\"[bold]Rate Limit Information:[/bold]\")\n+ if \"limit\" in rate_info:\n+ lines.append(f\" • Rate Limit: {rate_info['limit']} requests/hour\")\n+ if \"remaining\" in rate_info:\n+ lines.append(f\" • Remaining: {rate_info['remaining']}\")\n+ if \"reset_local\" in rate_info:\n+ reset_str = rate_info[\"reset_local\"].strftime(\"%Y-%m-%d %H:%M:%S %Z\")\n+ lines.append(f\" • Resets at: {reset_str}\")\n+ if \"retry_after_seconds\" in rate_info:\n+ lines.append(f\" • Retry after: {rate_info['retry_after_seconds']} seconds\")\n+ lines.append(\"\")\n+ \n+ # Add troubleshooting guidance\n+ lines.append(\"[bold]Troubleshooting Tips:[/bold]\")\n+ lines.append(\" • If you're on a shared CI or corporate environment, you may be rate-limited.\")\n+ lines.append(\" • Consider using a GitHub token via --github-token or the GH_TOKEN/GITHUB_TOKEN\")\n+ lines.append(\" environment variable to increase rate limits.\")\n+ lines.append(\" • Authenticated requests have a limit of 5,000/hour vs 60/hour for unauthenticated.\")\n+ \n+ return \"\\n\".join(lines)\n+\n # Agent configuration with name, folder, install URL, and CLI tool requirement\n AGENT_CONFIG = {\n \"copilot\": {\n@@ -577,10 +635,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri\n )\n status = response.status_code\n if status != 200:\n- msg = f\"GitHub API returned {status} for {api_url}\"\n+ # Format detailed error message with rate-limit info\n+ error_msg = _format_rate_limit_error(status, response.headers, api_url)\n if debug:\n- msg += f\"\\nResponse headers: {response.headers}\\nBody (truncated 500): {response.text[:500]}\"\n- raise RuntimeError(msg)\n+ error_msg += f\"\\n\\n[dim]Response body (truncated 500):[/dim]\\n{response.text[:500]}\"\n+ raise RuntimeError(error_msg)\n try:\n release_data = response.json()\n except ValueError as je:\n@@ -627,8 +686,11 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri\n headers=_github_auth_headers(github_token),\n ) as response:\n if response.status_code != 200:\n- body_sample = response.text[:400]\n- raise RuntimeError(f\"Download failed with {response.status_code}\\nHeaders: {response.headers}\\nBody (truncated): {body_sample}\")\n+ # Handle rate-limiting on download as well\n+ error_msg = _format_rate_limit_error(response.status_code, response.headers, download_url)\n+ if debug:\n+ error_msg += f\"\\n\\n[dim]Response body (truncated 400):[/dim]\\n{response.text[:400]}\"\n+ raise RuntimeError(error_msg)\n total_size = int(response.headers.get('content-length', 0))\n with open(zip_path, 'wb') as f:\n if total_size == 0:\n@@ -1202,6 +1264,85 @@ def check():\n if not any(agent_results.values()):\n console.print(\"[dim]Tip: Install an AI assistant for the best experience[/dim]\")\n \n+@app.command()\n+def version():\n+ \"\"\"Display version and system information.\"\"\"\n+ import platform\n+ import importlib.metadata\n+ \n+ show_banner()\n+ \n+ # Get CLI version from package metadata\n+ cli_version = \"unknown\"\n+ try:\n+ cli_version = importlib.metadata.version(\"specify-cli\")\n+ except Exception:\n+ # Fallback: try reading from pyproject.toml if running from source\n+ try:\n+ import tomllib\n+ pyproject_path = Path(__file__).parent.parent.parent / \"pyproject.toml\"\n+ if pyproject_path.exists():\n+ with open(pyproject_path, \"rb\") as f:\n+ data = tomllib.load(f)\n+ cli_version = data.get(\"project\", {}).get(\"version\", \"unknown\")\n+ except Exception:\n+ pass\n+ \n+ # Fetch latest template release version\n+ repo_owner = \"github\"\n+ repo_name = \"spec-kit\"\n+ api_url = f\"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest\"\n+ \n+ template_version = \"unknown\"\n+ release_date = \"unknown\"\n+ \n+ try:\n+ response = client.get(\n+ api_url,\n+ timeout=10,\n+ follow_redirects=True,\n+ headers=_github_auth_headers(),\n+ )\n+ if response.status_code == 200:\n+ release_data = response.json()\n+ template_version = release_data.get(\"tag_name\", \"unknown\")\n+ # Remove 'v' prefix if present\n+ if template_version.startswith(\"v\"):\n+ template_version = template_version[1:]\n+ release_date = release_data.get(\"published_at\", \"unknown\")\n+ if release_date != \"unknown\":\n+ # Format the date nicely\n+ try:\n+ dt = datetime.fromisoformat(release_date.replace('Z', '+00:00'))\n+ release_date = dt.strftime(\"%Y-%m-%d\")\n+ except Exception:\n+ pass\n+ except Exception:\n+ pass\n+\n+ info_table = Table(show_header=False, box=None, padding=(0, 2))\n+ info_table.add_column(\"Key\", style=\"cyan\", justify=\"right\")\n+ info_table.add_column(\"Value\", style=\"white\")\n+\n+ info_table.add_row(\"CLI Version\", cli_version)\n+ info_table.add_row(\"Template Version\", template_version)\n+ info_table.add_row(\"Released\", release_date)\n+ info_table.add_row(\"\", \"\")\n+ info_table.add_row(\"Python\", platform.python_version())\n+ info_table.add_row(\"Platform\", platform.system())\n+ info_table.add_row(\"Architecture\", platform.machine())\n+ info_table.add_row(\"OS Version\", platform.version())\n+\n+ panel = Panel(\n+ info_table,\n+ title=\"[bold cyan]Specify CLI Information[/bold cyan]\",\n+ border_style=\"cyan\",\n+ padding=(1, 2)\n+ )\n+\n+ console.print(panel)\n+ console.print()\n+\n def main():\n app()\n \ndiff --git a/templates/commands/clarify.md b/templates/commands/clarify.md\nindex 9a62dfa74..4de842aa6 100644\n--- a/templates/commands/clarify.md\n+++ b/templates/commands/clarify.md\n@@ -1,5 +1,9 @@\n ---\n description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json --paths-only\n ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly\ndiff --git a/templates/commands/constitution.md b/templates/commands/constitution.md\nindex f557dd17c..cf81f08c2 100644\n--- a/templates/commands/constitution.md\n+++ b/templates/commands/constitution.md\n@@ -1,5 +1,9 @@\n ---\n-description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync\n+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.\n+handoffs: \n+ - label: Build Specification\n+ agent: speckit.specify\n+ prompt: Implement the feature specification based on the updated constitution. I want to build...\n ---\n \n ## User Input\ndiff --git a/templates/commands/implement.md b/templates/commands/implement.md\nindex 38601920d..fde3651e2 100644\n--- a/templates/commands/implement.md\n+++ b/templates/commands/implement.md\n@@ -135,4 +135,3 @@ You **MUST** consider the user input before proceeding (if not empty).\n - Report final status with summary of completed work\n \n Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running/speckit.tasksfirst to regenerate the task list.\n-\ndiff --git a/templates/commands/plan.md b/templates/commands/plan.md\nindex 7dfe63a2f..147da0afa 100644\n--- a/templates/commands/plan.md\n+++ b/templates/commands/plan.md\n@@ -1,5 +1,13 @@\n ---\n description: Execute the implementation planning workflow using the plan template to generate design artifacts.\n+handoffs: \n+ - label: Create Tasks\n+ agent: speckit.tasks\n+ prompt: Break the plan into tasks\n+ send: true\n+ - label: Create Checklist\n+ agent: speckit.checklist\n+ prompt: Create a checklist for the following domain...\n scripts:\n sh: scripts/bash/setup-plan.sh --json\n ps: scripts/powershell/setup-plan.ps1 -Json\ndiff --git a/templates/commands/specify.md b/templates/commands/specify.md\nindex 69258a8bf..3f0ddb78b 100644\n--- a/templates/commands/specify.md\n+++ b/templates/commands/specify.md\n@@ -1,5 +1,13 @@\n ---\n description: Create or update the feature specification from a natural language feature description.\n+handoffs: \n+ - label: Build Technical Plan\n+ agent: speckit.plan\n+ prompt: Create a plan for the spec. I am building with...\n+ - label: Clarify Spec Requirements\n+ agent: speckit.clarify\n+ prompt: Clarify specification requirements\n+ send: true\n scripts:\n sh: scripts/bash/create-new-feature.sh --json \"{ARGS}\"\n ps: scripts/powershell/create-new-feature.ps1 -Json \"{ARGS}\"\ndiff --git a/templates/commands/tasks.md b/templates/commands/tasks.md\nindex 4663c1b67..86a766829 100644\n--- a/templates/commands/tasks.md\n+++ b/templates/commands/tasks.md\n@@ -1,5 +1,14 @@\n ---\n description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.\n+handoffs: \n+ - label: Analyze For Consistency\n+ agent: speckit.analyze\n+ prompt: Run a project analysis for consistency\n+ send: true\n+ - label: Implement Project\n+ agent: speckit.implement\n+ prompt: Start the implementation in phases\n+ send: true\n scripts:\n sh: scripts/bash/check-prerequisites.sh --json\n ps: scripts/powershell/check-prerequisites.ps1 -Json\ndiff --git a/templates/commands/taskstoissues.md b/templates/commands/taskstoissues.md\nnew file mode 100644\nindex 000000000..e0f366372\n--- /dev/null\n+++ b/templates/commands/taskstoissues.md\n@@ -0,0 +1,31 @@\n+---\n+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.\n+tools: ['github/github-mcp-server/create_issue']\n+scripts:\n+ sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks\n+ ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks\n+---\n+\n+## User Input\n+\n+```text\n+$ARGUMENTS\n+```\n+\n+You **MUST** consider the user input before proceeding (if not empty).\n+\n+## Outline\n+\n+1. Run{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").\n+1. From the executed script, extract the path to tasks.\n+1. Get the Git remote by running:\n+\n+bash\n+git config --get remote.origin.url\n+\n+\n+ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL\n+\n+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.\n+\n+UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL\n",
"metadata": {
"problem_domain": "Bug Fixes",
"difficulty": "high",
"estimated_review_effort": 4
}
}