feat: add Claude Code toolkit for UMS v2.0 development#84
Conversation
Summary of ChangesHello @synthable, I'm Gemini Code Assist1! 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 significantly upgrades the Unified Module System (UMS) to version 2.0 within Claude Code by integrating a powerful toolkit. This toolkit provides developers with a suite of specialized AI agents and custom commands designed to automate and streamline the entire UMS development lifecycle, from module creation and validation to build system maintenance and library curation. The changes aim to enhance developer productivity, ensure spec compliance, and improve the overall quality and consistency of UMS modules and personas. Highlights
Ignored Files
Using Gemini Code AssistThe 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
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 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
|
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a comprehensive toolkit of specialized agents and custom commands for working with the Unified Module System v2.0 in Claude Code, along with significant enhancements to the underlying UMS library to support the v2.0 specification.
Key changes include:
- Addition of 5 specialized agents for build development, library curation, module generation, validation, and persona validation
- Introduction of 6 custom commands for UMS v2.0 workflows including audit, build, create, curate, and validation operations
- Major update of the UMS library from v1.0 to v2.0 with new component-based architecture, TypeScript support, and pure functional APIs
Reviewed Changes
Copilot reviewed 78 out of 97 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
.claude/agents/*.md |
Defines 5 specialized agents with high autonomy for UMS v2.0 workflows |
.claude/commands/*.md |
Implements 6 custom commands for interactive and batch UMS operations |
packages/ums-lib/src/core/ |
Complete rewrite to v2.0 with modular architecture, pure functions, and TypeScript support |
packages/copilot-instructions-cli/src/ |
Updates CLI to support TypeScript modules and v2.0 specification |
| Configuration files | Updates for v2.0 compatibility and new module discovery patterns |
Comments suppressed due to low confidence (1)
packages/copilot-instructions-cli/src/utils/typescript-loader.ts:1
- The comment indicates that using filename as module ID is temporary and may need refinement. This could lead to incorrect module loading if the actual module ID doesn't match the filename. Consider implementing proper module ID extraction from the module content.
/**
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| const reportModule: BuildReportModule = { | ||
| id: module.id, | ||
| name: module.metadata.name, | ||
| version: module.version, | ||
| source: 'Local', // TODO: Distinguish between Standard Library and Local |
There was a problem hiding this comment.
The TODO comment indicates incomplete functionality for distinguishing module sources. This could lead to inaccurate build reports. Consider implementing proper source type detection or removing the TODO if this is intentional for the current implementation.
| const reportModule: BuildReportModule = { | |
| id: module.id, | |
| name: module.metadata.name, | |
| version: module.version, | |
| source: 'Local', // TODO: Distinguish between Standard Library and Local | |
| // Determine module source type | |
| let sourceType = 'Local'; | |
| if (module.metadata.source) { | |
| sourceType = module.metadata.source; | |
| } else if (module.id.startsWith('std:') || module.metadata.name?.startsWith('std-')) { | |
| sourceType = 'Standard Library'; | |
| } | |
| const reportModule: BuildReportModule = { | |
| id: module.id, | |
| name: module.metadata.name, | |
| version: module.version, | |
| source: sourceType, |
| entry.ids.forEach(() => { | ||
| const module = modules[moduleIndex++]; |
There was a problem hiding this comment.
The forEach callback doesn't use the module ID parameter, which could lead to incorrect module ordering if the entry.ids array doesn't match the order in the modules array. The code assumes modules are in the same order as entry.ids, but this isn't guaranteed.
|
|
||
| describe('ModuleRegistry', () => { | ||
| let registry: ModuleRegistry; | ||
| let consoleWarnSpy: ReturnType<typeof vi.spyOn>; |
There was a problem hiding this comment.
The consoleWarnSpy variable is declared but never used in the tests. Consider removing it or adding tests that verify warning behavior.
| let consoleWarnSpy: ReturnType<typeof vi.spyOn>; |
| // UMS v2.0 specification constants | ||
| export const UMS_SCHEMA_VERSION = '2.0'; |
There was a problem hiding this comment.
The schema version is updated to '2.0' but there are still references to v1.0 patterns elsewhere in the codebase (like shape specifications and validation logic). Ensure all schema-related code is consistently updated to v2.0.
| let rate: number; | ||
| let eta: number; | ||
| let etaSeconds: number; | ||
| if (elapsed > 0) { | ||
| rate = this.current / elapsed; // items per ms | ||
| eta = rate > 0 ? remaining / rate : Infinity; // ms remaining | ||
| etaSeconds = Math.round(eta / 1000); | ||
| } else { | ||
| rate = 0; | ||
| eta = Infinity; | ||
| etaSeconds = 0; |
There was a problem hiding this comment.
[nitpick] The variables rate, eta, and etaSeconds are declared but not initialized before the conditional check. While they are assigned in both branches, this pattern could be clearer by initializing them at declaration or restructuring the logic.
| let rate: number; | |
| let eta: number; | |
| let etaSeconds: number; | |
| if (elapsed > 0) { | |
| rate = this.current / elapsed; // items per ms | |
| eta = rate > 0 ? remaining / rate : Infinity; // ms remaining | |
| etaSeconds = Math.round(eta / 1000); | |
| } else { | |
| rate = 0; | |
| eta = Infinity; | |
| etaSeconds = 0; | |
| let rate: number = 0; | |
| let eta: number = Infinity; | |
| let etaSeconds: number = 0; | |
| if (elapsed > 0) { | |
| rate = this.current / elapsed; // items per ms | |
| eta = rate > 0 ? remaining / rate : Infinity; // ms remaining | |
| etaSeconds = Math.round(eta / 1000); |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This is an impressive and substantial pull request that introduces a comprehensive toolkit for UMS v2.0 development and refactors the existing system to be more robust and maintainable. The move to a TypeScript-first UMS v2.0, the clear separation of concerns between the pure ums-lib and the CLI, and the introduction of specialized agents and commands are all excellent improvements. The new architecture with a conflict-aware ModuleRegistry and pure functions for parsing, validation, and rendering is very well-designed. My feedback focuses on a few key areas to further enhance the architecture and documentation quality.
| * Implements build report generation per UMS v2.0 specification Section 7.3 | ||
| */ | ||
|
|
||
| import { createHash } from 'node:crypto'; |
There was a problem hiding this comment.
The ums-lib is described as platform-agnostic, but this file imports and uses the Node.js-specific node:crypto module. This will prevent the library from running in non-Node.js environments like browsers or Deno. To maintain platform independence, the digest generation logic should be moved out of this pure library. I suggest modifying generateBuildReport to accept pre-computed digests as arguments, and moving the hashing functions (generatePersonaDigest, generateModuleDigest) to the CLI package, which is the appropriate layer for platform-specific implementations.
| ````markdown | ||
| ## Knowledge | ||
|
|
||
| {explanation} | ||
|
|
||
| ### Key Concepts | ||
|
|
||
| **{concept.name}**: {description} | ||
| _Why_: {rationale} | ||
|
|
||
| ### Examples | ||
|
|
||
| #### {example.title} | ||
|
|
||
| {rationale} | ||
|
|
||
| ```{language} | ||
| {snippet} | ||
| ``` | ||
| ```` | ||
|
|
||
| ```` | ||
|
|
||
| **Data Component:** | ||
| ```markdown | ||
| ## Data | ||
|
|
||
| {description} | ||
|
|
||
| ```{format} | ||
| {value} | ||
| ```` | ||
|
|
||
| ```` |
There was a problem hiding this comment.
The fenced code blocks in this file are using four backticks () instead of the standard three (```). This can lead to incorrect rendering in many markdown viewers. Please correct all instances of ` to ``` for proper formatting. This issue is also present in other new markdown files in the.claude/` directory.
| if (missingModules.length > 0) { | ||
| throw new Error(`Missing modules: ${missingModules.join(', ')}`); | ||
| } |
There was a problem hiding this comment.
When missing modules are detected, a generic Error is thrown. The project has a well-defined set of custom error types in ums-lib (like BuildError). Using a more specific error type here would improve consistency and allow for more granular error handling in the handleError utility.
throw new BuildError(`Missing modules: ${missingModules.join(', ')}`);Add a comprehensive toolkit of specialized agents and custom commands for working with the Unified Module System v2.0 in Claude Code. Agents (5 specialized assistants): - build-developer: Develop and maintain the UMS v2.0 build system - library-curator: Curate and organize standard library modules - module-generator: Generate UMS v2.0 compliant modules - module-validator: Validate module compliance with spec - persona-validator: Validate persona structure and composition Commands (6 workflows): - /ums:audit - Comprehensive compliance and quality auditing - /ums:build - Build system development and maintenance - /ums:create - Interactive module and persona creation - /ums:curate - Library organization and maintenance - /ums:validate-module - Module validation workflows - /ums:validate-persona - Persona validation workflows Documentation: - .claude/AGENTS.md: Complete agent reference guide - .claude/COMMANDS.md: Complete command reference guide These tools provide: - Guided workflows for common UMS operations - Automated validation and quality assurance - Interactive creation with best practices - Build system development support - Library maintenance and curation - Comprehensive spec compliance checking All agents operate at high autonomy and follow UMS v2.0 specification strictly. Commands provide convenient entry points that delegate to specialized agents for complex tasks.
synthable
force-pushed
the
feat/ums-v2-toolkit
branch
from
5e67984 to
86409a7
Compare
- Fix mismatched and orphaned four-backtick sequences - Ensure proper escaping of triple backticks in markdown examples - build-developer.md: Fix Data Component and Build Report Generator examples - ums:validate-module.md: Fix Single Module FAIL example Addresses PR #84 review comment about incorrect four-backtick usage.
Summary
This PR introduces a comprehensive toolkit of specialized agents and custom commands for working with the Unified Module System v2.0 in Claude Code. The toolkit streamlines UMS development workflows from module creation to validation to build system maintenance.
What's New
🤖 Specialized Agents (5)
Agents are autonomous AI assistants with deep expertise in specific UMS domains:
1. build-developer
2. library-curator
3. module-generator
4. module-validator
5. persona-validator
⚡ Custom Commands (6)
Commands provide convenient workflows that delegate to specialized agents:
/ums:audit/ums:build/ums:create/ums:curate/ums:validate-module/ums:validate-persona📚 Documentation (2 comprehensive guides)
.claude/AGENTS.md(comprehensive agent reference).claude/COMMANDS.md(comprehensive command reference)Key Features
🎯 Guided Workflows
🔄 High Autonomy
📊 Quality Focus
🛠️ Developer Experience
Files Changed
New Files (4,111 lines added)
Documentation:
.claude/AGENTS.md(comprehensive agent guide).claude/COMMANDS.md(comprehensive command guide)Agents (5 files):
.claude/agents/build-developer.md.claude/agents/library-curator.md.claude/agents/module-generator.md.claude/agents/module-validator.md.claude/agents/persona-validator.mdCommands (6 files):
.claude/commands/ums:audit.md.claude/commands/ums:build.md.claude/commands/ums:create.md.claude/commands/ums:curate.md.claude/commands/ums:validate-module.md.claude/commands/ums:validate-persona.mdUsage Examples
Create a New Module
Validate All Foundation Modules
Audit Entire Library
Build System Development
Benefits
For Module Authors
For Maintainers
For Build System Developers
For All Contributors
Agent Workflows
Module Creation Pipeline
Quality Assurance Workflow
Build System Development
Testing
Compatibility
feat/ums-lib-v2Future Enhancements
Potential future additions:
Checklist
Next Steps
After merging:
/ums:createfor guided module creation/ums:auditfor quality assurance/ums:buildfor system developmentThis toolkit establishes a powerful, user-friendly development environment for UMS v2.0! 🚀
Documentation: See
.claude/AGENTS.mdand.claude/COMMANDS.mdfor complete usage guides.