create-collector

Create a new collector bot package with automatic implementation and validation.

Usage

/create-collector <vendor> <suite?> <product>

Arguments:

• vendor (required) - Vendor name (e.g., amazon, microsoft, google)
• suite (optional) - Suite name if vendor has suites (e.g., aws, 365)
• product (required) - Product name (e.g., iam, s3, entra)

Examples:

/create-collector amazon aws s3
/create-collector microsoft entra
/create-collector google workspace sheets
/create-collector adp workforcenowng

Description

End-to-end collector creation with automatic validation:

1. Verify module and schema dependencies exist
2. Create directory structure and configuration files
3. Generate code (npm install + generate)
4. Spawn 2 creation agents in parallel (Implementation + Mapping)
5. Create documentation (README, USERGUIDE)
6. Build and lint
7. Automatically validate with /review-collector
8. Fix critical issues or report to user
9. Ready for commit

Execution Instructions for Claude

Phase 1: Parse Arguments & Verify

Step 1.1: Parse vendor/suite/product

const args = args.trim().split(/\s+/);
// Examples:
// "amazon aws s3" → vendor=amazon, suite=aws, product=s3
// "microsoft entra" → vendor=microsoft, suite=null, product=entra
// "adp workforcenowng" → vendor=adp, suite=null, product=workforcenowng

Step 1.2: Verify dependencies exist

# Check module exists (prefer zerobias-org, fallback auditlogic)
npm view @zerobias-org/module-<vendor>-<suite?>-<product>
npm view @auditlogic/module-<vendor>-<suite?>-<product>

# Or check bundles
npm view @zerobias-org/module-bundle --json | jq '.dependencies'
npm view @auditlogic/module-bundle --json | jq '.dependencies'

# Check schema exists (always auditlogic)
npm view @auditlogic/schema-<vendor>-<suite?>-<product>

# Or check bundle
npm view @auditlogic/schema-bundle --json | jq '.dependencies'

# Check product exists (always zerobias-org)
npm view @zerobias-org/product-<vendor>-<suite?>-<product>

# Or check bundle
npm view @zerobias-org/product-bundle --json | jq '.dependencies'

If missing: STOP and inform user that module/schema/product must be created first.

Phase 2: Create Structure

Step 2.1: Create directory

mkdir -p package/<vendor>/<suite?>/<product>
cd package/<vendor>/<suite?>/<product>

Step 2.2: Create symlinks

# Based on depth (3 or 4 levels)
ln -s ../../../../.npmrc .npmrc    # or ../../../
ln -s ../../../../.nvmrc .nvmrc    # or ../../../

Step 2.3: Copy templates

# Copy from reference collector (adp/workforcenowng for simple)
cp ../../../adp/workforcenowng/.eslintrc .
cp ../../../adp/workforcenowng/.mocharc.json .
cp ../../../adp/workforcenowng/tsconfig.json .

Step 2.4: Create .gitignore

node_modules/
dist/
generated/

Phase 3: Create Configuration Files

Step 3.1: Create package.json (use template from DEVELOPMENT_WORKFLOW.md)

• Version: 0.0.0
• Author: [email protected]
• Dependencies: module + schema (base + ts) + core deps
• Get latest versions from npm

Step 3.2: Get UUIDs and create hub.yml

npm install  # Temporary to get module installed
cat node_modules/@auditlogic/module-*/package.json | grep module-id
cat node_modules/@auditlogic/product-*/index.yml | grep "^id:"

Create hub.yml with UUIDs (operations section omitted).

Step 3.3: Ask user about parameters "What parameters should this collector accept (if any)?"

• If none: use minimal template
• If provided: create with user's parameters

Step 3.4: Explore schema and create collector.yml

cat node_modules/@auditlogic/schema-*/dist/index.d.ts
cat node_modules/@auditlogic/module-*/module-*.yml

Match operations to classes and include ALL classes with module data.

Step 3.5: Generate code

npm install
npm run generate

Verify generated/BaseClient.ts and get module connector name.

Phase 4: Spawn Creation Agents (PARALLEL)

CRITICAL: Spawn BOTH agents in a SINGLE message with 2 Task calls.

Agent 1: Implementation Agent

• Read .claude/agents/create-implementation.md
• Pass: collector path, module connector name, schema classes, vendor type
• Creates: src/index.ts, src/Collector*Impl.ts

Agent 2: Mapping Agent

• Read .claude/agents/create-mappings.md
• Pass: collector path, module types, schema types, schema classes
• Creates: src/Mappers.ts

Wait for both to complete.

Phase 5: Create Documentation

Step 5.1: Create README.md

• What data is collected
• Schema classes
• Required permissions
• Development commands

Step 5.2: Create USERGUIDE.md (if has parameters)

• Only document parameters
• Customer-facing tone
• How to find values
• Example JSON

**Step 5.3: Create test/integration/Collector*IT.ts**

• Copy pattern from similar collector
• Adjust class name and parameters

Phase 6: Build & Lint

npm run build
npm run lint

If errors: attempt to fix common issues, otherwise report to user.

Phase 7: Validate with /review-collector

CRITICAL: Automatically run the validation system.

/review-collector .

This spawns all 8 validation agents.

If compliance < 90%:

• Report issues to user
• Ask if they want auto-fix for simple issues
• Critical issues (data loss, data deletion): Must be fixed before commit

If compliance >= 90%:

• Report minor issues as warnings
• Proceed to finalization

Phase 8: Finalize

Step 8.1: Run npm shrinkwrap

npm shrinkwrap

Step 8.2: Report to user

Display summary:

✅ Collector created: @zerobias-org/collectorbot-<vendor>-<suite?>-<product>

📦 Package: package/<vendor>/<suite?>/<product>

📊 Validation Results:
   ✅ Configuration: PASS
   ✅ Schema: PASS
   ✅ Mapping: PASS
   ✅ Pagination: PASS
   ✅ GroupId: PASS
   ✅ Security: PASS
   ✅ Performance: PASS
   ✅ Dependencies: PASS

   📈 Compliance: 100%

🎉 Collector is ready for commit!

📝 Next steps:
   1. Review the implementation in src/
   2. Test with: npm run test:integration
   3. Commit with: git commit -m "feat(s3): initial S3 collector"

If issues found:

⚠️  Collector created with issues (Compliance: 75%)

Issues found:
   ❌ Mapping: 2 errors
   ⚠️  Performance: 1 warning

Run /review-collector to see details.

Would you like me to fix these issues automatically?

Notes

• Implementation and Mapping agents can share documentation with validation agents
• Validation is AUTOMATIC - no manual step needed
• Creates production-ready collector in one command
• User only needs to review and commit