mirror of
https://github.com/nodnarbnitram/claude-code-extensions.git
synced 2026-09-14 18:36:21 +08:00
Brandon Martin
2232aae10c
## Summary - remove explicit `agents`, `skills`, and `commands` fields from generated plugin manifests - rely on Claude Code's standard auto-discovery for plugin-root `agents/`, `skills/`, and `commands/` directories - flatten packaged agents to `agents/*.md` so discovery does not depend on nested-path recursion - keep the fix minimal by only retaining the explicit `hooks` entry for `cce-core` ## Why A local plugin install failed with: ```text Plugin has an invalid manifest file ... Validation errors: agents: Invalid input ``` Our packaged plugins already follow the standard directory structure, so the extra manifest path fields were unnecessary and were the most likely validator mismatch. Greptile also flagged that many generated plugin agents were nested under paths like `agents/specialized/...`, which could silently fail if discovery is non-recursive. This change aligns the packages with the default plugin structure instead of relying on special manifest fields or recursive discovery. ## Changes - update `scripts/sync_plugin_packages.py` to stop emitting manifest path overrides - flatten generated packaged agents to plugin-root `agents/*.md` - regenerate all packaged plugin manifests with minimal metadata-only manifests - regenerate all packaged plugin agent files into the flat standard layout ## Verification - `python3 scripts/sync_plugin_packages.py` - `python3 -m py_compile scripts/sync_plugin_packages.py install_extensions.py` - validated all 19 generated plugin manifests as JSON - confirmed no generated manifest still contains `agents`, `skills`, or `commands` - confirmed packaged agents are flat: `flat_agents=78 nested_agents=0`
cce-temporal
Temporal.io workflow development across Python, Go, and TypeScript SDKs with comprehensive testing and troubleshooting support.
Overview
The cce-temporal plugin provides a complete suite of specialized agents for Temporal.io development, covering all major SDKs and critical development workflows. Whether you're building durable workflows in Python, Go, or TypeScript, this plugin provides expert guidance on implementation, testing, and troubleshooting.
Features
Multi-SDK Support
- Python SDK (v1.18.0+): AsyncIO patterns, pytest testing, activity execution modes
- Go SDK (v1.36.0+): Workflow-safe primitives, determinism patterns, testsuite framework
- TypeScript SDK (v1.13.0+): Type-safe proxyActivities, Jest testing, Promise patterns
Comprehensive Agent Suite
This plugin includes 6 specialized agents that automatically activate based on context:
- temporal-core: Universal Temporal concepts and architecture patterns
- temporal-python: Python SDK specialist for async/await patterns
- temporal-go: Go SDK specialist for workflow-safe concurrency
- temporal-typescript: TypeScript SDK specialist for type-safe development
- temporal-testing: Cross-SDK testing strategies and patterns
- temporal-troubleshooting: Error diagnosis and production debugging
Key Capabilities
- Workflow Development: Implement deterministic workflows following best practices
- Activity Patterns: Create idempotent activities with proper retry strategies
- Testing Strategies: Unit tests, integration tests, replay tests, and CI/CD setup
- Troubleshooting: Diagnose non-determinism, payload limits, history size issues
- Performance: Optimize schedule-to-start latency and worker efficiency
- Architecture: Saga patterns, Continue-As-New, child workflow partitioning
Installation
Via Plugin Marketplace
# Add the CCE marketplace (if not already added)
/plugin marketplace add https://github.com/nodnarbnitram/claude-code-extensions
# Install the Temporal plugin
/plugin install cce-temporal@cce-marketplace
From Local Repository
# Clone the repository
git clone https://github.com/nodnarbnitram/claude-code-extensions.git
cd claude-code-extensions
# Add local marketplace
/plugin marketplace add /path/to/claude-code-extensions
# Install plugin
/plugin install cce-temporal@cce-marketplace
Usage
The agents in this plugin activate automatically based on context. You can also explicitly invoke them:
Automatic Activation
The agents will automatically activate when you:
- Ask about Temporal workflows, activities, or architecture
- Request help with Python/Go/TypeScript SDK implementation
- Need testing strategies or debugging assistance
- Mention specific Temporal concepts (determinism, signals, queries, etc.)
Explicit Invocation
You can call agents directly using the @ syntax:
@temporal-core explain workflow versioning strategies
@temporal-python help me implement an async workflow
@temporal-go fix this map iteration non-determinism
@temporal-typescript configure proxyActivities with type safety
@temporal-testing create pytest tests with time-skipping
@temporal-troubleshooting diagnose this "workflow task failed" error
Command Namespacing
Commands are namespaced as /cce-temporal:*:
# Example: If future commands are added
/cce-temporal:workflow-init
/cce-temporal:test-replay
Agent Details
temporal-core
Universal Temporal expert for core concepts applicable across all SDKs
Covers:
- Workflows vs Activities decision matrix
- Task queues and routing patterns
- Determinism requirements and anti-patterns
- Retry policies and error handling
- Versioning strategies (Worker Versioning, Patching)
- Continue-As-New pattern for long-running workflows
- Saga pattern for distributed transactions
temporal-python
Python SDK specialist (v1.18.0+)
Covers:
- Async/await patterns with AsyncIO
- Activity execution modes (async, threaded, multiprocess)
- Common pitfalls: blocking libraries, gevent incompatibility
- Pytest integration with WorkflowEnvironment
- Time-skipping for long-duration workflows
- Exception handling with ApplicationError
- Type hints and dataclass patterns
temporal-go
Go SDK specialist (v1.36.0+)
Covers:
- Workflow-safe primitives (workflow.Go, workflow.Channel, workflow.Select)
- Map iteration determinism (sorting required)
- Context patterns (workflow.Context vs context.Context)
- Interface-based activity definitions
- Testing with testsuite package
- Selector pattern for multi-channel operations
- Common non-determinism errors
temporal-typescript
TypeScript SDK specialist (v1.13.0+)
Covers:
- Type-safe proxyActivities with full inference
- defineSignal/defineQuery patterns
- Jest testing configuration (Node environment required)
- Common pitfalls: missing startToCloseTimeout
- Monorepo package structure (@temporalio/*)
- Promise-based async patterns
- Time-skipping tests with TestWorkflowEnvironment
temporal-testing
Cross-SDK testing specialist
Covers:
- Testing pyramid (unit, integration, replay tests)
- Time-skipping for fast workflow tests
- Activity mocking strategies
- Replay testing against production histories
- CI/CD integration (GitHub Actions, GitLab CI)
- Docker Compose test environments
- Signal/query testing patterns
temporal-troubleshooting
Error diagnosis and debugging specialist
Covers:
- Non-determinism error diagnosis (most common issue)
- Workflow task failures and infinite retries
- Payload size limit errors (2MB/4MB/50MB limits)
- History size limit errors (51,200 events / 50MB)
- AsyncIO blocking issues (Python-specific)
- Performance troubleshooting (schedule-to-start latency)
- Temporal Web UI and CLI debugging tools
Common Workflows
Creating a New Workflow
# Python example - agent provides complete guidance
> I need to create a workflow that processes payments with retry logic
# The temporal-python agent will guide you through:
# 1. Workflow definition with @workflow.defn
# 2. Activity implementation for payment processing
# 3. Proper timeout configuration
# 4. Retry policies
# 5. Error handling with ApplicationError
# 6. Pytest tests with mocked activities
Debugging Non-Determinism
> I'm getting "Workflow execution history doesn't match workflow definition"
# The temporal-troubleshooting agent will:
# 1. Identify common non-deterministic patterns
# 2. Check for time/random functions
# 3. Verify workflow-safe primitives usage
# 4. Suggest replay testing setup
# 5. Provide SDK-specific fixes
Testing Strategies
> How do I test a workflow that sleeps for 7 days?
# The temporal-testing agent will:
# 1. Demonstrate time-skipping environments
# 2. Provide complete test examples for your SDK
# 3. Show activity mocking patterns
# 4. Configure CI/CD integration
# 5. Set up replay testing
SDK Version Compatibility
- Python: v1.18.0+ (requires Python 3.9+, 3.13 supported)
- Go: v1.36.0+ (built-in slog integration)
- TypeScript: v1.13.0+ (monorepo structure with @temporalio/* packages)
Best Practices Enforced
The agents in this plugin enforce Temporal best practices:
- Determinism First: All workflow code must be deterministic
- Activities for Side Effects: External calls, I/O, non-deterministic operations go in activities
- Idempotent Activities: Design for unlimited retries by default
- Proper Timeouts: Always set activity timeouts (especially TypeScript)
- Continue-As-New: Implement for workflows approaching history limits
- Replay Testing: Test code changes against production histories before deployment
- Type Safety: Leverage SDK type systems (especially TypeScript)
- Testing Pyramid: 70% unit, 20% integration, 10% E2E tests
Troubleshooting
Common Issues
"Agents not loading"
- Verify plugin installed:
/plugin list - Check installation:
/plugin install cce-temporal@cce-marketplace - Restart Claude Code session
"Wrong agent activating"
- Agents delegate based on context
- Explicitly invoke with
@temporal-<agent-name> - Core agent delegates to SDK specialists automatically
"Missing SDK-specific guidance"
- Mention your SDK explicitly: "using Python SDK" or "TypeScript Temporal"
- Check SDK version compatibility above
- SDK specialists auto-activate on SDK keywords
Contributing
This plugin is part of the claude-code-extensions project.
To contribute:
- Fork the repository
- Create agents in
${CLAUDE_PLUGIN_ROOT}/agents/specialized/temporal/ - Update plugin manifest if adding new agents
- Test with
/plugin validate . - Submit pull request
Documentation
Official Temporal Docs
Agent Reference
All agents are documented with:
- When to use (description field)
- Core competencies
- Common patterns
- Anti-patterns to avoid
- Delegation strategy
See agent source files in ${CLAUDE_PLUGIN_ROOT}/agents/specialized/temporal/ for complete documentation.
License
MIT License - See repository LICENSE file for details.
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Temporal Community: community.temporal.io
Changelog
v1.0.0 (Initial Release)
- 6 specialized agents covering all major SDKs
- Universal architecture guidance (temporal-core)
- Python SDK specialist (v1.18.0+)
- Go SDK specialist (v1.36.0+)
- TypeScript SDK specialist (v1.13.0+)
- Comprehensive testing strategies
- Production troubleshooting and debugging