feat(zcode): add ZCode as supported tool

[fyeeme]

Register ZCode in the AI tools registry and provide a command adapter so openspec init --tools zcode generates per-project artifacts under a single .zcode/ root (no split across .agents + .zcode):

• Skills: .zcode/skills/openspec-*/SKILL.md (ZCode-native discovery path, highest priority among project-level skill roots)
• Commands: .zcode/commands/opsx/.md (Claude-compatible frontmatter)

Both .zcode/skills and .agents/skills are valid ZCode discovery roots (verified from ZCode source: skillRootsForBase registers them in pairs); we use .zcode to keep all artifacts under one directory.

ZCode auto-detection triggers on .zcode or .agents at the project root.

Verification:

• pnpm build passes (TypeScript compiles clean)
• pnpm lint passes (no new warnings)
• pnpm test: 1661 tests pass (no regressions)
• E2E: openspec init --tools zcode --profile core produces 5 skills + 5 commands, all under .zcode/ (no .agents created)

Closes #1242. Supersedes #1243.

Summary by CodeRabbit

• New Features
  • Added ZCode as a supported tool integration and enabled it via tool configuration.
  • Auto-detect ZCode projects when a .zcode directory is present (without being affected by .agents alone).
  • Generate ZCode command output under .zcode/commands/opsx/ with YAML frontmatter, including robust escaping/quoting for special characters.
  • Added ZCode support for init and update flows.
• Documentation
  • Updated supported tools docs to include ZCode and its tool ID.
• Tests
  • Expanded coverage for ZCode detection, file generation, and formatting/escaping behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds ZCode as a supported AI tool with YAML-frontmatter command generation, registry and configuration wiring, documentation, tool-detection coverage, and initialization/update workflow tests.

Changes

ZCode Tool Integration

Layer / File(s)	Summary
ZCode adapter implementation with YAML escaping src/core/command-generation/adapters/zcode.ts, test/core/command-generation/adapters.test.ts	Implements YAML escaping, tag-array formatting, .zcode/commands/opsx/<id>.md paths, and command frontmatter rendering. Tests cover formatting and escaping edge cases.
Configuration, registry, and tool detection src/core/config.ts, src/core/command-generation/registry.ts, test/core/command-generation/registry.test.ts, test/core/available-tools.test.ts	Adds ZCode configuration, registers zcodeAdapter, and tests registry lookups and .zcode-based detection alongside .agents behavior.
Documentation and workflow validation docs/supported-tools.md, test/core/init.test.ts, test/core/update.test.ts	Documents ZCode paths and tool IDs, and tests initialization and update generation under .zcode without creating .agents.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• #1242: Adds the requested ZCode support through configuration, adapter registration, command generation, documentation, and workflow coverage.
• #1210: Similar objective of adding support for a new AI tool through configuration, adapter registration, and documentation.

Possibly related PRs

• Fission-AI/OpenSpec#1276: Extends the same adapter registry, AI_TOOLS, test, and documentation integration points for another tool.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant InitCommand
  participant CommandAdapterRegistry
  participant zcodeAdapter
  participant FileSystem
  CLI->>InitCommand: select zcode
  InitCommand->>CommandAdapterRegistry: resolve zcode adapter
  CommandAdapterRegistry-->>InitCommand: return zcodeAdapter
  InitCommand->>zcodeAdapter: format command frontmatter
  zcodeAdapter->>FileSystem: write .zcode/commands/opsx/<id>.md

Loading

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding ZCode support.
Linked Issues check	✅ Passed	The PR adds ZCode support via registry, adapter, config, docs, and tests, meeting #1242.
Out of Scope Changes check	✅ Passed	All changes are directly related to ZCode support and verification, with no obvious unrelated additions.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alfred-openspec]

Thanks for the scoped ZCode support. The adapter/config shape looks plausible and a local smoke generated the expected .zcode/skills/... plus .zcode/commands/opsx/*.md files, but this adds a new supported tool without focused regression coverage.

Please add tests that lock down the ZCode contract before merge: adapter path/frontmatter escaping, registry presence, .zcode + .agents auto-detection semantics, and init/update generation staying under .zcode without creating .agents. The existing broad tests pass, but they do not protect the new adapter path/detection behavior.

[fyeeme]

Unit tests have been added and all passed. The configuration of the zcode directory has also been fixed. @alfred-openspec

[alfred-openspec]

Thanks for the quick cleanup. I rechecked the updated head: detection is now scoped to .zcode, the new adapter/registry/init/update coverage is in place, and the focused local tests passed. The remaining YAML helper dedupe is already tracked separately in #1204/#1205, so I do not think it should block this adapter.

[alfred-openspec]

The adapter now has focused path and frontmatter, registry, detection, init, and update coverage, and the .zcode/commands/opsx namespace matches current ZCode ecosystem conventions. The rebase and full CI are green.

[clay-good]

Merged main into this branch (62248ee): unioned the tool-ID list in docs/supported-tools.md (hermes + zcode) and kept both the ZCode init test and the renamed Kimi Code test from #1208. Affected suites (304 tests) pass locally. @alfred-openspec please re-review.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

test/core/update.test.ts (1)

216-218: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use path.join for filesystem paths in output expectations.

Hard-coding Unix path separators (/) in CLI output expectations can cause tests to fail on Windows, where native paths use backslashes (\). As per coding guidelines, use path.join to build expected path values to ensure cross-platform consistency.

💻 Proposed fix

-      expect(logCalls.some((entry) => entry.includes('.kimi/skills') && entry.includes('.kimi-code/skills'))).toBe(true);
+      expect(logCalls.some((entry) => entry.includes(path.join('.kimi', 'skills')) && entry.includes(path.join('.kimi-code', 'skills')))).toBe(true);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/core/update.test.ts` around lines 216 - 218, Update the output assertion
in the logCalls expectation to construct both filesystem path fragments with
path.join rather than hard-coding “/” separators, while preserving the existing
requirement that the entry contains both .kimi/skills and .kimi-code/skills
paths.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@test/core/update.test.ts`:
- Around line 216-218: Update the output assertion in the logCalls expectation
to construct both filesystem path fragments with path.join rather than
hard-coding “/” separators, while preserving the existing requirement that the
entry contains both .kimi/skills and .kimi-code/skills paths.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 36b0f6e4-0c9e-4dc9-9169-0e035e118e4e

📥 Commits

Reviewing files that changed from the base of the PR and between 5f0c6db and 62248ee.

📒 Files selected for processing (6)

• docs/supported-tools.md
• src/core/config.ts
• test/core/available-tools.test.ts
• test/core/command-generation/registry.test.ts
• test/core/init.test.ts
• test/core/update.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/supported-tools.md
• src/core/config.ts
• test/core/command-generation/registry.test.ts

[alfred-openspec]

Verified the latest rebase preserves Hermes in the supported-tool list, the renamed Kimi Code test from main, and the full ZCode contract: scoped .zcode detection, adapter path/frontmatter, registry wiring, and init/update generation without .agents leakage. The final diff is clean, mergeable, and fully green across Windows, macOS, and Linux.