feat: Add UMS v2.0 Toolkit Plugin for Claude Code

[synthable]

Summary

Adds a comprehensive plugin-based development toolkit for UMS v2.0 module and persona development in Claude Code.

What's Included

Plugin Structure

• 5 Specialized Agents: Module validator, persona validator, module generator, build developer, library curator
• 6 Slash Commands: /ums:create, /ums:validate-module, /ums:validate-persona, /ums:audit, /ums:curate, /ums:build
• 3 Reusable Procedures: Complete module workflow, quality audit workflow, library addition workflow
• Complete Documentation: Plugin README with usage examples and best practices

Key Features

Agents

1. module-validator: Validates modules against UMS v2.0 specification
2. persona-validator: Validates persona composition and quality
3. module-generator: Interactive wizard for creating new modules
4. build-developer: Develops build system functionality
5. library-curator: Manages standard library organization and metrics

Commands

• /ums:create - Launch interactive module creation wizard
• /ums:validate-module [path] - Validate single module, directory, or entire tier
• /ums:validate-persona [path] - Validate single persona or all personas
• /ums:audit - Parallel validation of all modules and personas with comprehensive report
• /ums:curate - Library management (add, remove, metrics, organize)
• /ums:build - Build system development tasks

Additional Files

• .claude/AGENTS.md - Complete agent documentation and usage patterns
• .claude/agents/github-cli-agent.md - GitHub CLI operations agent
• Updated modules.config.yml to point to instruct-modules-v2/

Benefits

• Comprehensive Quality Assurance: Automated validation of all modules and personas
• Accelerated Development: Interactive wizards and templates for module creation
• Library Management: Tools for organizing and curating the standard library
• Consistent Standards: Ensures all modules follow UMS v2.0 specification
• Developer Experience: Specialized agents and commands for common workflows

Test Plan

• Plugin structure follows Claude Code plugin conventions
• All agent files have proper frontmatter and documentation
• Commands have clear descriptions and usage examples
• Procedures define complete workflows
• Plugin manifest (plugin.yml) is valid
• Pre-commit hooks pass (typecheck, lint, format)

Breaking Changes

None - this is an additive change that provides new development tooling.

Dependencies

• Based on: feat/ums-lib-v2 branch (commit 586d843)
• Requires: UMS v2.0 library and SDK (from parent branch)

Related

• Part of UMS v2.0 migration initiative
• Complements PR feat: Implement UMS v2.0 with TypeScript support #78 (core v2.0 implementation)
• Provides development tooling for v2.0 module authors

Notes

• The toolkit is designed to work with TypeScript .module.ts and .persona.ts files
• All agents are scoped to the ums: namespace to avoid conflicts
• Procedures can be composed for complex workflows

[gemini-code-assist]

Summary of Changes

Hello @synthable, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive UMS v2.0 Toolkit Plugin for Claude Code, designed to streamline the development and maintenance of UMS v2.0 modules and personas. It transitions the system from YAML-based UMS v1.0 to a TypeScript-first approach for enhanced type safety and developer experience. The toolkit provides a suite of specialized agents, slash commands, and reusable workflows to automate module creation, validation, library curation, and build system development, significantly improving quality assurance and accelerating development cycles within the UMS v2.0 ecosystem.

Highlights

• UMS v2.0 Toolkit Plugin: Introduced a comprehensive plugin for Claude Code, featuring 5 specialized agents (Module Validator, Persona Validator, Module Generator, Build Developer, Library Curator), 6 slash commands (/ums:create, /ums:validate-module, /ums:validate-persona, /ums:audit, /ums:curate, /ums:build), and 3 reusable procedures for streamlined UMS v2.0 development.
• TypeScript-First Approach: Migrated UMS modules and personas from YAML-based v1.0 to a TypeScript-first v2.0, enhancing type safety, developer experience, and IDE support across the system.
• CLI Updates: Updated the copilot-instructions-cli to support UMS v2.0 TypeScript files, including new commands for MCP server interaction and a revised validate command that now directs users to TypeScript compiler for validation.
• Core Library Rework: The ums-lib core library underwent a significant rewrite to align with UMS v2.0, updating type definitions, parsing, validation, rendering, and resolution logic to support the new component-based module structure and persona composition.
• Documentation Overhaul: Refreshed documentation to reflect the UMS v2.0 specification, new toolkit features, and the updated monorepo structure, removing outdated UMS v1.0 guides and processes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Copilot]

Pull Request Overview

This PR implements the complete migration from UMS v1.0 to v2.0, featuring a comprehensive plugin-based development toolkit for Claude Code and updated type system. The changes span across multiple packages, transforming the system from YAML-based v1.0 to TypeScript-native v2.0.

Key changes:

• Complete type system migration to UMS v2.0 specification with TypeScript-first approach
• Addition of comprehensive UMS v2.0 Toolkit Plugin for Claude Code with 5 specialized agents and 6 slash commands
• Enhanced CLI with TypeScript module loading, MCP server support, and improved error handling

Reviewed Changes

Copilot reviewed 81 out of 82 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
vitest.config.ts	Adds test coverage exclusions for CLI entry points and test utilities
packages/ums-mcp/src/index.ts	New MCP server entry point supporting multiple transport protocols
packages/ums-lib/src/	Complete v2.0 type system migration with new component-based architecture
packages/copilot-instructions-cli/src/	Enhanced CLI with TypeScript loading and MCP integration
modules.config.yml	Updates module path to point to v2.0 modules directory

Comments suppressed due to low confidence (1)

packages/copilot-instructions-cli/src/utils/module-discovery.ts:1

• This is a significant behavioral change from the previous version. Consider updating the function documentation to clearly indicate this breaking change and provide migration guidance for users who relied on automatic standard module discovery.

/**

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Consider using a more specific error type for validation errors. The function should throw a ValidationError or ModuleParseError instead of a generic Error to maintain consistency with the rest of the codebase error handling patterns.

[Copilot]

The function has eslint-disable comments for complexity and max-lines-per-function, indicating it may be doing too much. Consider breaking this into smaller, focused validation functions (e.g., validateModuleStructure, validateMetadata, validateComponents) to improve maintainability and testability.

[Copilot]

Similar to the module validator, this function exceeds the max-lines-per-function limit. Consider extracting validation logic into separate functions like validatePersonaMetadata, validateModuleEntries, etc.

[Copilot]

While the runtime check is necessary for external data validation, consider using a type guard function to make this pattern reusable and improve code clarity. This would also eliminate the need for the eslint-disable comment.

[Copilot]

Same as the persona validator - consider creating a reusable type guard function for metadata validation to improve code consistency and eliminate the need for eslint-disable comments.

[gemini-code-assist]

Code Review

This is a massive and impressive pull request that successfully migrates the Unified Module System from v1.0 (YAML-based) to v2.0 (TypeScript-based). The introduction of the Claude Code Toolkit Plugin with its specialized agents, commands, and workflows is a huge step forward for developer experience and quality assurance. The code changes are extensive and well-executed, particularly the refactoring of the ums-lib to support the new v2.0 spec, the improved error handling, and the new TypeScript loader. The documentation is thorough and provides a great foundation for developers. I have a few suggestions for improvement, mainly around consistency in documentation and a potential change in module discovery behavior that needs clarification. Overall, excellent work on a very significant feature.

[gemini-code-assist]

The agent's declared tools seem to contradict its operational guidelines. The frontmatter lists Write and Edit as available tools, but the "File modifications" guideline on line 113 states that the agent is "read-only for repository files". To adhere to the principle of least privilege and avoid potential misuse, the agent should only be granted the tools it is actually supposed to use. If file modifications are indeed deferred, the Write and Edit tools should be removed.

Suggested change

	tools: Bash, Read, Write, Edit, Grep, Glob
	tools: Bash, Read, Grep, Glob

[gemini-code-assist]

The agent name in the frontmatter is github-agent, but it's referred to as github-cli-agent in AGENTS.md and the PR description. For consistency and clarity, it would be better to use the more descriptive name github-cli-agent here as well.

Suggested change

	name: github-agent
	name: github-cli-agent

[gemini-code-assist]

This example seems to be incomplete. The user's request is shown, but there is no corresponding agent response or action. It would be helpful to complete this example to demonstrate how the system would handle the request.

[gemini-code-assist]

The template uses a hardcoded relative path ../../../types/index.js for imports. This might be brittle, as it assumes a fixed directory depth for all generated modules. It would be more robust if the module generator could calculate the correct relative path based on the destination of the generated file, or use path aliases if the project supports them.

[gemini-code-assist]

The regex pattern for the module id in this documentation appears to be less strict than the one defined in the core library (packages/ums-lib/src/constants.ts). The documentation should reflect the actual regex used for validation to avoid confusion for developers. The core library regex correctly enforces that the ID must start with one of the valid tiers (foundation, principle, etc.).

Suggested change

	id: string, // Pattern: ^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$
	id: string, // Pattern: ^(foundation|principle|technology|execution)\/([a-z0-9-]+(?:\/[a-z0-9-]+)*\/[a-z0-9][a-z0-9-]*|[a-z0-9][a-z0-9-]*)$

[gemini-code-assist]

The name of this test file is module-parser.test.ts, but the tests within seem to be for validateModule, which resides in module-validator.ts. For better maintainability and clarity, the test file should be renamed to module-validator.test.ts to accurately reflect the code it's testing. Alternatively, if it's intended to test the parser, the tests should target parseModuleObject.

[synthable]

Closing in favor of PR #84 which uses a direct integration approach (flat .claude/agents/ and .claude/commands/ structure) instead of the plugin wrapper approach. PR #84 is the preferred architecture.