@uluops/setup 0.2.0

package/assets/commands/workflows/ship.md

@@ -0,0 +1,721 @@
+---
+name: ship
+description: Final gate before shipping. Runs 5 core phases (Validate → Type Safety → Test Architect → Code Auditor → Public Interface → Security) plus conditional API Contract/Release Readiness. Persists all recommendations to tracker.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# Ship Pipeline
+
+Final gate before shipping. Runs 5 core phases (Validate → Type Safety → Test Architect → Code Auditor → Public Interface → Security) plus conditional API Contract/Release Readiness. Persists all recommendations to tracker.
+
+
+**Philosophy**: The final gate before shipping—smart enough to know what checks your project needs.
+
+---
+
+## Workflow Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  CORE PHASES (Always Run)                                                   │
+│  ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌───────┐   ┌──────┐         │
+│  │Validate│─▶│ Type │─▶│ Test │─▶│ Code │─▶│Public │─▶│Security│         │
+│  │ Code  │  │Safety*│  │Architect│ │Auditor│  │Interface│  │ Audit │         │
+│  └──────┘   └──────┘   └──────┘   └──────┘   └───────┘   └──────┘         │
+│      │          │          │          │           │           │             │
+│      ▼          ▼          ▼          ▼           ▼           ▼             │
+│   PASS/     SAFE/     APPROVED/   SOUND/     POLISHED/    SECURE/          │
+│   FAIL      UNSAFE*   IMPROVE     UNSOUND    CLEANUP      BLOCKED          │
+│                                                                             │
+│  * Type Safety runs only if tsconfig.json exists                           │
+│                                                                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  CONDITIONAL PHASES (Based on Project Type)                                 │
+│                                                                             │
+│  IF API Routes Detected:        IF Publishable Package:                     │
+│  ┌───────────┐                  ┌─────────────┐                            │
+│  │API Contract│                  │Release Ready │                           │
+│  └───────────┘                  └─────────────┘                            │
+│       │                               │                                     │
+│       ▼                               ▼                                     │
+│   CONSISTENT/                     READY/                                    │
+│   DRIFT                           NOT READY                                 │
+│                                                                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  OUTPUTS (Always Run - regardless of pass/fail)                             │
+│                                                                             │
+│      ┌──────────────────┐          ┌──────────────────┐                    │
+│      │  Features List   │          │  Save to Tracker │                    │
+│      │  (markdown)      │          │  (MCP tool)      │                    │
+│      └────────┬─────────┘          └────────┬─────────┘                    │
+│               └──────────┬─────────────────┘                               │
+│                          ▼                                                  │
+│               ┌──────────────────┐                                         │
+│               │  Post-Save       │                                         │
+│               │  Verification    │                                         │
+│               └──────────────────┘                                         │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+```
+
+[TS] = Runs if tsconfig.json detected (TypeScript project)
+[API] = Runs if REST routes detected (Express/router patterns)
+[PKG] = Runs if publishable package (not private)
+
+Duration: 8-20 minutes (varies with project type)
+**Important:** Even in parallel mode, if ANY agent in a group fails with a blocking result, stop the pipeline and report all results collected so far.
+
+---
+
+## Agent Handoff Formats
+
+Each agent passes structured data to the next in the pipeline:
+
+| From | To | Passes | Expects |
+|------|-----|--------|---------|
+| Code Validator | Type Safety | File list, error baseline, complexity metrics | Type-specific issues beyond basic linting |
+| Code Validator | Test Architect | Test file locations, coverage baseline | Test quality assessment beyond coverage % |
+| Code Validator | Public Interface | Export list, module structure | Documentation accuracy, unused code detection |
+| Test Architect | Code Auditor | Test confidence level, covered paths | Runtime bugs in areas tests miss |
+| Code Auditor | Security | Code quality baseline, async patterns | OWASP compliance, vulnerability scan |
+| Security | API Contract | Security-cleared codebase | Contract drift on secure API |
+| Security | Release Readiness | Security-cleared package | Version and publishing readiness |
+
+**Handoff Contract:**
+- Each agent accepts predecessor's score and blockers
+- Agents don't re-check validated areas (trust predecessors)
+- Critical failures propagate as pipeline blockers
+- All findings feed into tracker persistence
+
+---
+
+## Pre-Flight: Target Detection and Configuration
+
+Before running agents, determine the target path and which optional validators should run.
+
+### Context Detection
+
+**Detection criteria**: A detector returns TRUE if its command exits with code 0.
+
+| Detector ID | Description |
+|-------------|-------------|
+| `typescript_detected` | Check if file exists: {{ target }}/tsconfig.json |
+| `package_json_detected` | Check if file exists: package.json |
+| `private_package` | Search for pattern ""private":\s*true" in package.json |
+| `api_routes_detected` | Search for pattern "router\.|app\.get|app\.post|app\.put|app\.delete" in *.ts, *.js |
+
+**typescript_detected**:
+```bash
+test -f "{{ target }}/tsconfig.json" && echo "DETECTED" || echo "NOT DETECTED"
+```
+
+**package_json_detected**:
+```bash
+test -f "package.json" && echo "DETECTED" || echo "NOT DETECTED"
+```
+
+**private_package**:
+```bash
+grep -rqE --include="package.json"  ""private":\s*true" . 2>/dev/null && echo "DETECTED" || echo "NOT DETECTED"
+```
+
+**api_routes_detected**:
+```bash
+grep -rqE --include="*.ts" --include="*.js"  "router\.|app\.get|app\.post|app\.put|app\.delete" . 2>/dev/null && echo "DETECTED" || echo "NOT DETECTED"
+```
+
+
+---
+
+## Arguments
+
+### Positional Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| directory | Yes | Target directory to validate |
+
+
+### Usage Examples
+
+| Command | Behavior |
+|---------|----------|
+| `/workflows:ship ./packages/bfl-api` | Validates package, detects API routes, runs full pipeline |
+| `/workflows:ship ./services/auth-service` | Service validation with API contract checks |
+| `/workflows:ship .` | Validates current directory |
+
+---
+
+## Execution Mode Selection
+
+**After completing project detection, ask the user to choose execution mode using AskUserQuestion:**
+
+| Mode | Description | Best For |
+|------|-------------|----------|
+| Sequential | Run agents one at a time, stop on first failure | Debugging, first runs, when you want early feedback |
+| Parallel | Run independent agents concurrently | Speed, CI/CD, when project is stable |
+
+**Parallel execution groups (when parallel mode selected):**
+
+```
+Group 1 (gate):     code-validator
+                           │
+                           ▼
+Group 2 (parallel):     type-safety + test-architect + public-interface
+                           │
+                           ▼
+Group 3 (sequential):     code-auditor
+                           │
+                           ▼
+Group 4 (gate):     security
+                           │
+                           ▼
+Group 5 (parallel):     api-contract + release-readiness
+                           │
+                           ▼
+Group 6 (always):     persist-to-tracker
+```
+
+**Note:** Conditional validators only run in their groups if detected in pre-flight.
+
+**Important:** Even in parallel mode, if ANY agent in a group fails with a blocking result, stop the pipeline and report all results collected so far.
+
+---
+
+## Execution
+
+Run each agent in sequence (or parallel groups if selected). Stop and fix if any agent fails. **Collect all recommendations for tracker persistence.**
+
+### Phase 1: Code Validation
+**Commands**: validate@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "validate",
+  prompt: "[validator:validate] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "Code Validator"
+)
+```
+
+**Gate**: threshold >= 70, on fail: stop
+
+**Focus**:
+- Code quality and standards compliance
+- Complexity and maintainability
+- Error handling patterns
+- Linting and formatting
+
+**Capture for tracker**: All findings, regardless of pass/fail status.
+
+**If failing**: Fix code quality issues before proceeding. Do not ship broken code.
+
+**Decision criteria**:
+- PASS (✅): Score ≥70 AND no auto-fail conditions
+- FAIL (❌): Score <70 OR auto-fail triggered
+
+---
+
+### Phase 2: Type Safety (Conditional)
+**Runs when**: `context.typescript_detected`
+
+**Commands**: type-safety@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "type-safety",
+  prompt: "[validator:type-safety] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "Type Safety Validator"
+)
+```
+
+**Gate**: threshold >= 80, warn if < 70, on fail: stop
+
+**Why this threshold?** Type holes in shipped code propagate to consumers. Stricter than post-impl because this is the final gate.
+
+**Focus**:
+- Explicit any usage and type holes
+- Type assertions without runtime guards
+- Strict mode compliance
+- Public API type quality
+
+**Capture for tracker**: All type safety issues, any abuse, unsafe assertions.
+
+**If failing**: Fix type holes before proceeding. Type safety issues compound—one any infects all downstream code.
+
+**Skip conditions**:
+- No tsconfig.json found
+- Pure JavaScript project
+
+**Decision criteria**:
+- SAFE (✅): Score ≥80 AND no any in public API
+- REVIEW (⚠️): Score 70-79 OR minor any usage with justification
+- UNSAFE (❌): Score <70 OR any in public API OR critical type holes
+
+**Auto-fail conditions**:
+- any in exported function signatures
+- Double assertions (as unknown as SomeType pattern)
+- strict: false in tsconfig for library code
+
+**Depends on**: code-validator
+
+---
+
+### Phase 3: Test Architecture Review
+**Commands**: test-review@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "test-review",
+  prompt: "[validator:test-review] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "Test Architect"
+)
+```
+
+**Gate**: threshold >= 70, on fail: stop
+
+**Focus**:
+- Test quality, not just coverage
+- False confidence patterns (mocks at wrong level)
+- Critical path coverage
+- Edge case handling
+
+**Capture for tracker**: All recommendations for test improvements.
+
+**If failing**: Improve tests before shipping. Ship pipeline requires higher test confidence.
+
+**Decision criteria**:
+- APPROVED (✅): Score ≥70 AND critical paths covered
+- IMPROVE (❌): Score <70 → Run /fix:test-gaps
+
+**Depends on**: code-validator
+
+---
+
+### Phase 4: Runtime Correctness Audit
+**Commands**: audit@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "audit",
+  prompt: "[validator:audit] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "Code Auditor"
+)
+```
+
+**Gate**: threshold >= 80, warn if < 70, on fail: stop
+
+**Why this threshold?** Code-auditor catches bugs that pass tests. Higher threshold because these are silent production failures.
+
+**Focus**:
+- Async hazards (unawaited promises in callbacks)
+- Null dereferences (.find() without null check)
+- Silent failures (empty catch blocks)
+- Error propagation gaps
+
+**Capture for tracker**: All runtime correctness issues with file:line references.
+
+**If failing**: Fix runtime bugs before shipping. These cause production incidents.
+
+**Decision criteria**:
+- SOUND (🔒): Score ≥80 AND no auto-fail conditions
+- REVIEW (🔍): Score 70-79
+- UNSOUND (⛔): Score <70 OR auto-fail triggered
+
+**Auto-fail conditions**:
+- Unawaited promise in error callback
+- .find() result used without null check
+- Empty catch block swallowing errors
+- JSON.parse without try/catch
+- HTTP response used without status check
+- Array access without bounds validation
+
+**Depends on**: test-architect
+
+---
+
+### Phase 5: Public Interface Validation
+**Commands**: public-interface@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "public-interface",
+  prompt: "[validator:public-interface] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "Public Interface Validator"
+)
+```
+
+**Gate**: threshold >= 75, on fail: stop
+
+**Focus**:
+- README accuracy and completeness
+- Export hygiene (unused exports, missing exports)
+- Documentation gaps
+- Code cleanliness (unused imports, dead code)
+
+**Capture for tracker**: All documentation gaps and hygiene issues.
+
+**If failing**: Update README, remove dead code, add JSDoc. Consumer-facing polish required for ship.
+
+**Decision criteria**:
+- POLISHED (✨): Score ≥75 AND README matches exports
+- NEEDS CLEANUP (🧹): Score <75
+
+**Depends on**: code-validator
+
+---
+
+### Phase 6: Security Audit
+**Commands**: security@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "security",
+  prompt: "[validator:security] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "Security Analyst"
+)
+```
+
+**Gate**: threshold >= 85, warn if < 70, on fail: stop
+
+**Why this threshold?** Security is the final gate. Shipping vulnerable code is unacceptable.
+
+**Focus**:
+- OWASP Top 10 compliance
+- Secrets and credentials exposure
+- Dependency vulnerabilities (npm audit)
+- Input validation and sanitization
+- Authentication and authorization patterns
+
+**Capture for tracker**: All security findings and recommendations.
+
+**If failing**: Fix security issues before shipping. Security is non-negotiable for production.
+
+**Decision criteria**:
+- SECURE (✅): Score ≥85 AND no auto-fail conditions
+- CONDITIONAL (⚠️): Score 70-84 → Review and document accepted risks
+- BLOCKED (❌): Score <70 OR auto-fail triggered
+
+**Auto-fail conditions**:
+- Hardcoded secrets/API keys in source code
+- SQL injection or command injection confirmed
+- Authentication bypass possible
+- Critical npm vulnerability (CVSS >= 9.0)
+- Secrets in git history
+- RCE vector identified
+
+**Depends on**: code-auditor
+
+---
+
+### Phase 7: API Contract Validation (Conditional)
+**Runs when**: `context.is_api_service`
+
+**Commands**: api-contract@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "api-contract",
+  prompt: "[validator:api-contract] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "API Contract Validator"
+)
+```
+
+**Gate**: threshold >= 80, on fail: stop
+
+**Focus**:
+- Documentation/implementation alignment
+- Type definitions match actual responses
+- Breaking changes detection
+- Endpoint completeness
+
+**Capture for tracker**: Contract drift issues and sync recommendations.
+
+**If failing**: Sync API contracts before shipping. Consumers depend on accurate documentation.
+
+**Skip conditions**:
+- No Express/router patterns detected
+- CLI tool only (no HTTP endpoints)
+
+**Decision criteria**:
+- CONSISTENT (✅): Score ≥80 AND no drift detected
+- DRIFT (⚠️): Score <80 → Sync contracts
+
+**Depends on**: security
+
+---
+
+### Phase 8: Release Readiness (Conditional)
+**Runs when**: `context.publishable_package`
+
+**Commands**: release@1.0.0
+
+**Invoke via Task tool:**
+```
+Task(
+  subagent_type: "release",
+  prompt: "[validator:release] Validate {TARGET_DIRECTORY}. Return structured JSON OUTPUT.",
+  description: "Release Readiness"
+)
+```
+
+**Gate**: threshold >= 80, warn if < 70, on fail: stop
+
+**Focus**:
+- Version consistency (CLI --version matches package.json)
+- CHANGELOG has current version entry
+- Build is fresh and matches source
+- Package.json completeness (main, types, exports)
+
+**Capture for tracker**: Version issues, documentation gaps, release hygiene items.
+
+**If failing**: Fix version and documentation issues before publishing.
+
+**Skip conditions**:
+- Private package (private: true)
+- No package.json
+- Internal tool only
+
+**Decision criteria**:
+- READY (✅): Score ≥80 AND versions match AND CHANGELOG current
+- WARNINGS (⚠️): Score 70-79 → Review, then continue
+- NOT READY (❌): Score <70
+
+**Depends on**: security
+
+---
+
+
+---
+
+## Summary Report
+
+After all phases complete, summarize:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Target: [path]
+Run: [N]
+
+┌─────────────────────┬────────┬────────────┐
+│ Agent               │ Score  │ Status     │
+├─────────────────────┼────────┼────────────┤
+│ ...                 │ [X]/100│ ✅/❌/⏭️   │
+└─────────────────────┴────────┴────────────┘
+
+```
+
+
+### Scoring
+
+**Method**: weighted_average
+
+| Phase | Weight |
+|-------|--------|
+| code-validator | 15% |
+| type-safety | 10% |
+| test-architect | 15% |
+| code-auditor | 20% |
+| public-interface | 10% |
+| security | 20% |
+| api-contract | 5% |
+| release-readiness | 5% |
+
+
+---
+
+## Final Phase: Outputs (MANDATORY)
+
+**This phase runs regardless of pass/fail status.** All agent recommendations must be captured.
+
+### Artifacts
+
+**features-list** (markdown):
+
+Generate a timestamp for the filename:
+
+```bash
+TIMESTAMP=$(date +%Y-%m-%dT%H-%M-%S)
+echo "Timestamp: $TIMESTAMP"
+```
+
+Write file to: `{{ target_path }}/{{ target_name }}-features-list-{{ timestamp }}.md`
+
+#### Granularity Rules
+
+**DO NOT consolidate multiple findings into single entries.** The tracker handles deduplication via fingerprinting. Save ALL raw findings:
+
+| Agent Reports | You Save |
+|---------------|----------|
+| "N+1 pattern in 14 locations" | 14 separate recommendations, one per file:line |
+| "Missing null checks on 8 .find() calls" | 8 separate recommendations |
+| "6 endpoints missing from docs" | 6 separate recommendations |
+
+**Rule:** If validator output has a file:line reference, it becomes a separate recommendation entry.
+
+### Save to Tracker (MANDATORY — Always Save First)
+
+**CRITICAL: Always save to the tracker. Never skip this step.**
+
+After writing the markdown file, save results via `mcp__uluops-tracker__save_features_list`:
+
+```
+mcp__uluops-tracker__save_features_list({
+  project: {{ target_name }},
+  workflow_type: "ship",
+  timestamp: {ISO8601 timestamp},
+  validators: [
+    {
+      "name": "{Agent Name}",
+      "score": {numeric},
+      "status": "{PASS|FAIL|SKIP}",
+      "model": "{haiku|sonnet|opus}"
+    }
+    // ... one entry per agent
+  ],
+  recommendations: [
+    {
+      "validator": "{agent-name}",
+      "title": "{short title}",
+      "priority": "{critical|suggested|backlog}",
+      "severity": "{critical|high|medium|low|info}",
+      "description": "{details}",
+      "file_path": "{path}",
+      "line_number": {number}
+    }
+    // ... one entry per recommendation
+  ]
+})
+```
+
+**Priority mapping:**
+- Blocking (fix before ship) → `"critical"`
+- Warnings (review before ship) → `"suggested"`
+- Post-ship/backlog items → `"backlog"`
+
+### Post-Save Verification
+
+After saving, verify the data was persisted correctly. **These are warnings, not blockers.**
+
+**Query uluops-tracker and compare to recommendations.length**
+
+- On mismatch: **warn** (do NOT block or re-attempt)
+- Saved count differs from payload count. This is normal when cross-phase deduplication occurs (multiple validators flag the same file:line). Log the discrepancy as a note—do NOT re-attempt or block.
+
+**Verify file exists: {{ target_path }}/{{ target_name }}-features-list-{{ timestamp }}.md**
+
+- On mismatch: **warn** (do NOT block or re-attempt)
+- Features list markdown file not found at expected path. Verify the write succeeded.
+
+**Verification procedure:**
+
+1. Query the tracker for the saved run
+2. Compare saved recommendation count against your payload count
+3. If counts differ, log the discrepancy as a note — cross-phase deduplication is expected when multiple validators flag the same issue
+4. **Proceed regardless** — the save already succeeded
+
+
+---
+
+
+
+
+
+
+---
+
+## Quick Reference
+
+| Agent | Threshold | Group |
+|-------|-----------|-------|
+| Code Validation | threshold >= 70, on fail: stop | 1 |
+| Type Safety | threshold >= 80, warn if < 70, on fail: stop | 2 |
+| Test Architecture Review | threshold >= 70, on fail: stop | 2 |
+| Runtime Correctness Audit | threshold >= 80, warn if < 70, on fail: stop | 3 |
+| Public Interface Validation | threshold >= 75, on fail: stop | 2 |
+| Security Audit | threshold >= 85, warn if < 70, on fail: stop | 4 |
+| API Contract Validation | threshold >= 80, on fail: stop | 5 |
+| Release Readiness | threshold >= 80, warn if < 70, on fail: stop | 5 |
+
+**Conditional Validator Activation**:
+- **Type Safety**: `context.typescript_detected`
+- **API Contract Validation**: `context.is_api_service`
+- **Release Readiness**: `context.publishable_package`
+
+---
+
+## Troubleshooting
+
+### Code Auditor keeps flagging async issues that seem fine
+
+Code Auditor uses Opus for deeper reasoning about async patterns. If it flags something, investigate carefully:
+- Unawaited promises in callbacks ARE a problem even if tests pass
+- .then() without .catch() can silently swallow errors
+- Fire-and-forget patterns need explicit documentation
+
+If the pattern is intentional, add a SAFETY comment explaining why.
+
+
+### Type Safety fails but tsc compiles fine
+
+The Type Safety validator checks beyond compilation:
+- any abuse that tsc allows but causes runtime issues
+- Type assertions that skip runtime validation
+- Implicit any from missing types
+
+tsc with strict mode catches some issues, but the validator looks for patterns that compile but cause consumer problems.
+
+
+### Security blocks on a dependency vulnerability I cannot upgrade
+
+If a dependency has a known vulnerability but upgrading would break things:
+1. Document the risk in the validation report
+2. Add a note explaining mitigation (if any)
+3. Consider the CONDITIONAL path (score 70-84) for documented accepted risks
+4. Create a tracking issue for the upgrade
+
+Never ignore security findings—document the decision.
+
+
+### Release Readiness says version mismatch but I use semantic-release
+
+With semantic-release CI/CD, versioning is automated. The validator may flag:
+- CLI --version showing different version (check if it reads from package.json dynamically)
+- CHANGELOG being auto-generated
+
+If you use semantic-release, these are expected. The validator will note "Release Strategy: Semantic Release CI/CD" and adjust expectations.
+
+
+### API Contract runs but I do not have OpenAPI docs
+
+API Contract validation checks alignment between:
+- JSDoc/TSDoc on route handlers
+- TypeScript types for request/response
+- Any README documentation about endpoints
+
+You don't need formal OpenAPI—the validator checks whatever documentation exists matches implementation.
+
+
+### Pipeline takes too long in parallel mode
+
+Even in parallel mode, groups run sequentially:
+1. Group 1 (gate) must complete first
+2. Group 2 (parallel) runs type-safety + test-architect + public-interface
+3. Group 3 runs code-auditor (needs test context)
+4. Group 4 runs security (final gate)
+5. Group 5 runs conditionals in parallel
+
+The bottleneck is usually code-auditor (Opus) and security. These cannot be parallelized because they depend on prior phases.
+
+