feat: add ZCode (Z.AI) integration by meymchen · Pull Request #3063 · github/spec-kit

meymchen · 2026-06-18T18:52:27Z

Summary

Adds a skills-based integration for ZCode (Z.AI), a Claude-Code-style coding agent. ZCode uses the same SKILL.md skill layout as Claude Code, and Z.AI's own docs recommend Skills (over simple / commands) for template- and script-driven workflows — which is exactly what spec-kit is.

Spec-kit workflows install into .zcode/skills/speckit-<name>/SKILL.md and are invoked in chat as $speckit-<name>.

Changes

src/specify_cli/integrations/zcode/__init__.py — new ZcodeIntegration(SkillsIntegration): folder .zcode/, skills dir .zcode/skills, context_file="ZCODE.md", requires_cli=True (key zcode matches the CLI executable), and a --skills option.
src/specify_cli/integrations/__init__.py — registered import + _register(ZcodeIntegration()) (alphabetical).
integrations/catalog.json — catalog entry, tags ["cli", "skills", "z-ai"].
tests/integrations/test_integration_zcode.py — SkillsIntegrationTests mixin (29 tests).
docs/reference/integrations.md + README.md — documentation.

Modeled directly on the existing Claude/Kimi skills integrations. Two low-risk defaults: context file ZCODE.md (consistent with the per-tool pattern; zcode docs don't pin one down) and minimal skill frontmatter (name, description) per zcode's documented format.

Testing

uv run pytest tests/integrations/test_integration_zcode.py → 29 passed
Full integration suite passes; the single failure in tests/test_extensions.py::TestCatalogStack::test_default_stack is pre-existing on main and unrelated to this change.

Manual test results

Agent: ZCode (via specify init) | OS/Shell: Linux/bash

Command tested	Notes
`specify init --integration zcode`	Scaffolds all 11 skills under `.zcode/skills/speckit-*/SKILL.md` with correct `name`/`description` frontmatter matching zcode's documented format.

AI assistance disclosure

This contribution was developed with AI assistance. The integration was researched against the zcode docs, implemented by mirroring existing skills-based integrations, and verified by me with the automated tests and the specify init smoke test above.

Add a skills-based integration for ZCode, Z.AI's Claude-Code-style agent. ZCode uses the same SKILL.md layout as Claude Code, so spec-kit installs workflows into .zcode/skills/speckit-<name>/SKILL.md, invoked in chat as $speckit-<name>. - ZcodeIntegration(SkillsIntegration) with .zcode/ folder and --skills option - Register in INTEGRATION_REGISTRY - Catalog entry (tags: cli, skills, z-ai) - Tests via SkillsIntegrationTests mixin - Document in integrations reference and README Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new built-in ZCode (Z.AI) skills-based integration to the Specify CLI, aiming to scaffold Spec Kit workflows into ZCode’s .zcode/skills/ layout and document how to invoke them.

Changes:

Introduces ZcodeIntegration (SkillsIntegration) with .zcode/skills output + ZCODE.md context file.
Registers the integration and adds it to the integrations catalog.
Adds minimal integration scaffolding tests and updates docs/README to list ZCode as supported.

Show a summary per file

File	Description
`src/specify_cli/integrations/zcode/__init__.py`	New `SkillsIntegration` subclass for ZCode with `.zcode/` folder and skills output configuration.
`src/specify_cli/integrations/__init__.py`	Registers `ZcodeIntegration()` in the built-in integration registry.
`integrations/catalog.json`	Adds the `zcode` entry to the published integration catalog.
`tests/integrations/test_integration_zcode.py`	Adds a `SkillsIntegrationTests`-mixin based test class for the new integration.
`docs/reference/integrations.md`	Documents ZCode as a supported agent and describes its skills layout/invocation.
`README.md`	Updates the “agent tools installed” list to include ZCode.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 6/6 changed files
Comments generated: 3

meymchen · 2026-06-21T17:35:18Z

 | [Trae](https://www.trae.ai/)                                                         | `trae`           | Skills-based integration; skills are installed automatically                                                                               |
 | [Windsurf](https://windsurf.com/)                                                    | `windsurf`       |                                                                                                                                           |
+| [ZCode](https://zcode.z.ai/)                                                         | `zcode`          | Skills-based integration; installs skills into `.zcode/skills/` and invokes them as `$speckit-<command>`                                  |
 | [Zed](https://zed.dev/)                                                              | `zed`            | Skills-based integration; installs skills into `.agents/skills` and invokes them as `/speckit-<command>`                                  |


Fixed in efc3cfd. The $speckit-* decision is now centralized in a DOLLAR_SKILLS_AGENTS set (codex + zcode) with an is_dollar_skills_agent() helper, and specify init Next Steps + extension hooks both route through it — so --integration zcode now renders $speckit-<command>, matching this docs row.

meymchen · 2026-06-21T17:35:20Z

+"""ZCode integration — skills-based agent (Z.AI).
+
+ZCode uses the ``.zcode/skills/speckit-<name>/SKILL.md`` layout, matching
+the Claude Code skill format. Skills are invoked in chat with
+``$speckit-<name>``. Z.AI recommends skills (over simple ``/`` commands)
+for template- and script-driven workflows such as spec-kit.


Fixed in efc3cfd. Added zcode to the new DOLLAR_SKILLS_AGENTS set in _invocation_style.py; specify init now reports "skills"/"Start ZCode" and renders $speckit-<cmd> in Next Steps, and HookExecutor._render_hook_invocation renders $speckit-<cmd> for hooks.

meymchen · 2026-06-21T17:35:22Z

+"""Tests for ZcodeIntegration — skills-based integration (Z.AI)."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestZcodeIntegration(SkillsIntegrationTests):
+    KEY = "zcode"
+    FOLDER = ".zcode/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".zcode/skills"
+    CONTEXT_FILE = "ZCODE.md"


Fixed in efc3cfd. Added ZCode invocation regression coverage mirroring the Codex/Kimi tests: test_zcode_hooks_render_dollar_skill_invocation (hook rendering) in test_extensions.py and TestZcodeInvocation.test_next_steps_show_dollar_skill_invocation in this file, asserting $speckit-* appears (and /speckit.* does not) in init Next Steps output.

mnriem

Please address Copilot feedback

ZCode is documented as a skills agent invoked with $speckit-<command>, but the central invocation rendering only special-cased codex, so specify init Next Steps and extension hooks rendered the dotted /speckit.<command> form instead. Centralize the $speckit-* decision in a DOLLAR_SKILLS_AGENTS set with an is_dollar_skills_agent() helper, and route both init Next Steps and HookExecutor._render_hook_invocation through it. Add ZCode invocation regression tests mirroring the existing Codex/Kimi coverage. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Copilot's findings

Files reviewed: 10/10 changed files
Comments generated: 4

+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=True,
+                help="Install as agent skills (default for ZCode)",
+            ),
+        ]


+from ..base import IntegrationOption, SkillsIntegration
+
+
+class ZcodeIntegration(SkillsIntegration):


 | [Tabnine CLI](https://docs.tabnine.com/main/getting-started/tabnine-cli)             | `tabnine`        |                                                                                                                                           |
 | [Trae](https://www.trae.ai/)                                                         | `trae`           | Skills-based integration; skills are installed automatically                                                                               |
 | [Windsurf](https://windsurf.com/)                                                    | `windsurf`       |                                                                                                                                           |
+| [ZCode](https://zcode.z.ai/)                                                         | `zcode`          | Skills-based integration; installs skills into `.zcode/skills/` and invokes them as `$speckit-<command>`                                  |


+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--integration", "zcode",
+                "--ignore-agent-tools", "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)


mnriem · 2026-06-22T15:09:04Z

Please address Copilot feedback

…egration # Conflicts: # src/specify_cli/extensions.py

meymchen requested a review from mnriem as a code owner June 18, 2026 18:52

mnriem requested a review from Copilot June 19, 2026 15:42

Copilot started reviewing on behalf of mnriem June 19, 2026 15:42 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

mnriem requested changes Jun 19, 2026

View reviewed changes

jawwad-ali mentioned this pull request Jun 21, 2026

feat: add Firebender integration (Android Studio / IntelliJ) #3077

Open

5 tasks

meymchen requested a review from mnriem June 21, 2026 17:37

mnriem requested a review from Copilot June 22, 2026 13:54

Copilot AI reviewed Jun 22, 2026

View reviewed changes

Copilot started reviewing on behalf of mnriem June 22, 2026 14:41 View session

Merge remote-tracking branch 'upstream/main' into feat/2975-zcode-int…

fbd6c6b

…egration # Conflicts: # src/specify_cli/extensions.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add ZCode (Z.AI) integration#3063

feat: add ZCode (Z.AI) integration#3063
meymchen wants to merge 3 commits into
github:mainfrom
meymchen:feat/2975-zcode-integration

meymchen commented Jun 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

meymchen Jun 21, 2026

Uh oh!

meymchen Jun 21, 2026

Uh oh!

meymchen Jun 21, 2026

Uh oh!

mnriem left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem commented Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		from ..base import IntegrationOption, SkillsIntegration


		class ZcodeIntegration(SkillsIntegration):

Conversation

meymchen commented Jun 18, 2026

Summary

Changes

Testing

Manual test results

AI assistance disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

meymchen Jun 21, 2026

Choose a reason for hiding this comment

Uh oh!

meymchen Jun 21, 2026

Choose a reason for hiding this comment

Uh oh!

meymchen Jun 21, 2026

Choose a reason for hiding this comment

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

mnriem commented Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants