workflow-agent-cli 1.1.2

package/templates/CUSTOM_SCOPE_TEMPLATE.md

@@ -0,0 +1,228 @@
+# Custom Scope Package Template
+
+This template provides boilerplate code for creating custom scope packages for the Workflow Agent.
+
+## Package Structure
+
+```
+scopes-{{scopeName}}/
+├── package.json       # Package metadata and dependencies
+├── tsconfig.json      # TypeScript configuration
+├── tsup.config.ts     # Build configuration
+└── src/
+    ├── index.ts       # Scope definitions and preset export
+    └── index.test.ts  # Test suite for scopes
+```
+
+## package.json Template
+
+```json
+{
+  "name": "@workflow/scopes-{{scopeName}}",
+  "version": "{{packageVersion}}",
+  "description": "Scope preset for {{presetName}}",
+  "keywords": ["workflow", "scopes", "{{scopeName}}", "preset"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/your-repo.git",
+    "directory": "{{packageDirectory}}"
+  },
+  "license": "MIT",
+  "author": "Your Name",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@hawkinside_out/workflow-agent": "^1.0.0"
+  },
+  "devDependencies": {
+    "@hawkinside_out/workflow-agent": "^1.0.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+## src/index.ts Template
+
+```typescript
+import type { Scope } from '@hawkinside_out/workflow-agent/config';
+
+export const scopes: Scope[] = {{scopeDefinitions}};
+
+export const preset = {
+  name: '{{presetName}}',
+  description: 'Scope configuration for {{presetName}}',
+  scopes,
+  version: '{{packageVersion}}',
+};
+
+export default preset;
+```
+
+## src/index.test.ts Template
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { scopes, preset } from './index.js';
+import { ScopeSchema } from '@hawkinside_out/workflow-agent/config';
+
+describe('{{presetName}} Scope Preset', () => {
+  it('should export valid scopes array', () => {
+    expect(scopes).toBeDefined();
+    expect(Array.isArray(scopes)).toBe(true);
+    expect(scopes.length).toBeGreaterThan(0);
+  });
+
+  it('should have valid preset object', () => {
+    expect(preset).toBeDefined();
+    expect(preset.name).toBe('{{presetName}}');
+    expect(preset.scopes).toBe(scopes);
+    expect(preset.version).toBeDefined();
+  });
+
+  it('should have no duplicate scope names', () => {
+    const names = scopes.map(s => s.name);
+    const uniqueNames = new Set(names);
+    expect(uniqueNames.size).toBe(names.length);
+  });
+
+  it('should have all scopes match schema', () => {
+    scopes.forEach(scope => {
+      const result = ScopeSchema.safeParse(scope);
+      if (!result.success) {
+        console.error(\`Scope "\${scope.name}" failed validation:\`, result.error);
+      }
+      expect(result.success).toBe(true);
+    });
+  });
+
+  it('should have descriptions for all scopes', () => {
+    scopes.forEach(scope => {
+      expect(scope.description).toBeDefined();
+      expect(scope.description.length).toBeGreaterThan(0);
+    });
+  });
+});
+```
+
+## tsconfig.json Template
+
+```json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+## tsup.config.ts Template
+
+```typescript
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+});
+```
+
+## Usage
+
+To create a custom scope package using these templates:
+
+1. **Use the CLI** (recommended):
+   ```bash
+   workflow scope:create
+   ```
+
+2. **Manual creation** (advanced):
+   - Copy this template structure
+   - Replace all `{{variable}}` placeholders
+   - Run `pnpm install && pnpm build && pnpm test`
+
+## Variables
+
+- `{{scopeName}}` - Package name (lowercase, alphanumeric with hyphens)
+- `{{presetName}}` - Display name for the preset
+- `{{scopeDefinitions}}` - JSON array of scope objects
+- `{{packageVersion}}` - Package version (default: "1.0.0")
+- `{{packageDirectory}}` - Relative path in repository
+- `{{isMonorepo}}` - "true" if in monorepo workspace
+
+## Scope Object Schema
+
+Each scope in `{{scopeDefinitions}}` must match:
+
+```typescript
+{
+  name: string;              // lowercase, alphanumeric, hyphens, max 32 chars
+  description: string;       // min 10 characters
+  emoji?: string;            // optional emoji
+  category?: 'auth' | 'features' | 'infrastructure' | 'documentation' | 
+             'testing' | 'performance' | 'other';
+}
+```
+
+## Example Scope Definitions
+
+```json
+[
+  {
+    "name": "auth",
+    "description": "Authentication and authorization features",
+    "emoji": "🔐",
+    "category": "auth"
+  },
+  {
+    "name": "billing",
+    "description": "Payment processing and subscription management",
+    "emoji": "💳",
+    "category": "features"
+  },
+  {
+    "name": "analytics",
+    "description": "Usage tracking and reporting features",
+    "emoji": "📊",
+    "category": "features"
+  }
+]
+```
+
+## Best Practices
+
+1. **Scope Count**: Aim for 8-15 scopes per preset
+2. **Naming**: Use clear, domain-specific names (avoid generic terms like "feature", "fix")
+3. **Descriptions**: Be specific about what each scope covers (minimum 10 characters)
+4. **Categories**: Use categories to group related scopes
+5. **Emojis**: Add visual identifiers to improve readability (optional)
+
+## Next Steps
+
+After creating your package:
+
+1. Build: `pnpm build`
+2. Test: `pnpm test`
+3. Publish: `pnpm publish --access public`
+4. Use: `pnpm add @workflow/scopes-{{scopeName}}`