claude-cli-advanced-starter-pack 1.0.16 → 1.8.0

package/templates/docs/PHASE-DEV-CHECKLIST.template.md

@@ -0,0 +1,241 @@
+# Phase Development Checklist
+
+Validation gates for phased development execution.
+
+## Overview
+
+Three levels of validation ensure quality at each development stage:
+
+- **L1**: Quick sanity checks (< 1 minute)
+- **L2**: Standard validation (1-5 minutes)
+- **L3**: Comprehensive verification (5+ minutes)
+
+---
+
+## L1 Validation (Quick Check)
+
+Run after each task completion.
+
+### Checklist
+
+- [ ] **Syntax Valid** - No parse errors
+- [ ] **Imports Resolve** - No missing modules
+- [ ] **Types Check** - No type errors (if TypeScript)
+- [ ] **Lint Clean** - No blocking lint errors
+
+### Commands
+
+```bash
+# JavaScript/TypeScript
+npx eslint --quiet <changed-files>
+npx tsc --noEmit
+
+# Python
+python -m py_compile <changed-files>
+ruff check <changed-files>
+```
+
+### Pass Criteria
+
+- Zero syntax errors
+- Zero type errors
+- Zero blocking lint errors
+
+---
+
+## L2 Validation (Standard Check)
+
+Run at phase completion, before phase advancement.
+
+### Checklist
+
+- [ ] **All L1 Checks Pass**
+- [ ] **Unit Tests Pass** - Affected tests run
+- [ ] **No Regressions** - Existing tests still pass
+- [ ] **Files Created** - Expected outputs exist
+- [ ] **Documentation Updated** - If API changed
+
+### Commands
+
+```bash
+# Run affected tests
+npm run test -- --findRelatedTests <changed-files>
+
+# Verify expected files
+ls -la <expected-output-files>
+
+# Check documentation
+grep -r "TODO: document" docs/
+```
+
+### Pass Criteria
+
+- All unit tests pass
+- Expected files exist
+- No TODO documentation items for changed APIs
+
+---
+
+## L3 Validation (Comprehensive Check)
+
+Run at project milestones, before deployment.
+
+### Checklist
+
+- [ ] **All L2 Checks Pass**
+- [ ] **Full Test Suite Pass** - All tests
+- [ ] **E2E Tests Pass** - Critical paths
+- [ ] **Performance Check** - No degradation
+- [ ] **Security Scan** - No vulnerabilities
+- [ ] **Build Succeeds** - Production build works
+
+### Commands
+
+```bash
+# Full test suite
+npm test
+
+# E2E tests
+npm run test:e2e
+
+# Performance audit
+npx lighthouse --output=json --quiet
+
+# Security scan
+npm audit
+npx snyk test
+
+# Production build
+npm run build
+```
+
+### Pass Criteria
+
+- 100% test pass rate
+- E2E tests cover critical paths
+- No high/critical vulnerabilities
+- Build completes without errors
+
+---
+
+## Phase-Specific Gates
+
+### Phase 1: Foundation
+
+| Gate | Criteria |
+|------|----------|
+| Structure | All directories created |
+| Config | Configuration files valid |
+| Dependencies | All packages installed |
+| Base Tests | Setup tests pass |
+
+### Phase 2: Implementation
+
+| Gate | Criteria |
+|------|----------|
+| Features | All tasks complete |
+| Coverage | >80% on new code |
+| Integration | API tests pass |
+| Types | Full type coverage |
+
+### Phase 3: Polish & Deploy
+
+| Gate | Criteria |
+|------|----------|
+| E2E | All flows tested |
+| Performance | Meets thresholds |
+| Security | No vulnerabilities |
+| Docs | Complete and current |
+
+---
+
+## Automated Gate Checks
+
+### PROGRESS.json Validation
+
+```json
+{
+  "validation_gates": {
+    "tasks_complete": true,
+    "files_created": true,
+    "tests_passing": true,
+    "no_errors": true,
+    "token_budget": true
+  }
+}
+```
+
+### Gate Runner Script
+
+```javascript
+// Run all gates for current phase
+async function runValidationGates(phase) {
+  const results = {
+    tasks_complete: await checkTasksComplete(phase),
+    files_created: await checkFilesCreated(phase),
+    tests_passing: await checkTestsPassing(phase),
+    no_errors: await checkNoErrors(phase),
+    token_budget: await checkTokenBudget(phase)
+  };
+
+  const allPassed = Object.values(results).every(r => r);
+
+  return { allPassed, results };
+}
+```
+
+---
+
+## Failure Handling
+
+### L1 Failure
+
+1. Fix immediately before proceeding
+2. Re-run L1 checks
+3. Continue with task
+
+### L2 Failure
+
+1. Identify failing gate
+2. Create remediation task
+3. Fix and re-validate
+4. Update PROGRESS.json
+
+### L3 Failure
+
+1. Document failure details
+2. Create tracking issue
+3. Roll back if needed
+4. Plan remediation
+5. Re-execute full L3
+
+---
+
+## Quick Commands
+
+```bash
+# L1 Quick Check
+npm run validate:l1
+
+# L2 Phase Check
+npm run validate:l2
+
+# L3 Comprehensive Check
+npm run validate:l3
+
+# All checks
+npm run validate:all
+```
+
+---
+
+## Integration with Phased Development
+
+1. **Task Complete** → Run L1
+2. **Phase Complete** → Run L2
+3. **Ready to Deploy** → Run L3
+4. **All Gates Pass** → Proceed to next phase
+
+---
+
+*Use these checklists to ensure quality at every stage*

package/templates/docs/PROGRESS_JSON_TEMPLATE.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "PROGRESS.json template for phased development tracking",
+  "version": "1.0.0",
+  "project_slug": "{{project.slug}}",
+  "project_name": "{{project.name}}",
+  "created_at": "{{date}}",
+  "last_updated": "{{date}}",
+  "current_phase": 1,
+  "overall_progress": {
+    "total_phases": 3,
+    "completed_phases": 0,
+    "total_tasks": 15,
+    "completed_tasks": 0,
+    "success_rate": 0.0
+  },
+  "phases": [
+    {
+      "phase_number": 1,
+      "title": "Foundation",
+      "status": "not_started",
+      "started_at": null,
+      "completed_at": null,
+      "tasks": [
+        {
+          "id": "P1-T1",
+          "title": "Task 1 description",
+          "status": "pending",
+          "priority": "high",
+          "estimated_tokens": 5000,
+          "actual_tokens": null,
+          "dependencies": [],
+          "files_to_modify": [],
+          "acceptance_criteria": [
+            "Criterion 1",
+            "Criterion 2"
+          ],
+          "notes": ""
+        },
+        {
+          "id": "P1-T2",
+          "title": "Task 2 description",
+          "status": "pending",
+          "priority": "medium",
+          "estimated_tokens": 3000,
+          "actual_tokens": null,
+          "dependencies": ["P1-T1"],
+          "files_to_modify": [],
+          "acceptance_criteria": [
+            "Criterion 1"
+          ],
+          "notes": ""
+        }
+      ],
+      "validation_gates": {
+        "tasks_complete": false,
+        "files_created": false,
+        "tests_passing": false,
+        "no_errors": false,
+        "token_budget": false
+      },
+      "expected_output_files": [],
+      "token_budget": 25000,
+      "require_tests": false
+    },
+    {
+      "phase_number": 2,
+      "title": "Implementation",
+      "status": "not_started",
+      "started_at": null,
+      "completed_at": null,
+      "tasks": [],
+      "validation_gates": {
+        "tasks_complete": false,
+        "files_created": false,
+        "tests_passing": false,
+        "no_errors": false,
+        "token_budget": false
+      },
+      "expected_output_files": [],
+      "token_budget": 50000,
+      "require_tests": true
+    },
+    {
+      "phase_number": 3,
+      "title": "Polish & Deploy",
+      "status": "not_started",
+      "started_at": null,
+      "completed_at": null,
+      "tasks": [],
+      "validation_gates": {
+        "tasks_complete": false,
+        "files_created": false,
+        "tests_passing": false,
+        "no_errors": false,
+        "token_budget": false
+      },
+      "expected_output_files": [],
+      "token_budget": 25000,
+      "require_tests": true
+    }
+  ],
+  "git_tracking": {
+    "pre_start_commit": null,
+    "phase_commits": [],
+    "current_stable_commit": null
+  },
+  "checkpoints": [],
+  "blockers": [],
+  "metadata": {
+    "scale": "M",
+    "estimated_total_tokens": 100000,
+    "actual_total_tokens": 0,
+    "success_target": 0.95,
+    "auto_chain_enabled": false
+  }
+}

package/templates/docs/background-agent.template.md

@@ -0,0 +1,264 @@
+# Background Agent Orchestration
+
+Template for production-grade background agent workflows.
+
+## Overview
+
+Background agents run autonomous tasks without blocking the main conversation. Use for:
+
+- Long-running operations (builds, tests, deployments)
+- Parallel exploration tasks
+- Batch processing
+- Monitoring and validation
+
+## Configuration
+
+### Basic Background Agent Launch
+
+```typescript
+// Launch agent in background
+const result = await Task({
+  description: "Run full test suite",
+  prompt: "Execute all tests and report results...",
+  subagent_type: "Bash",
+  run_in_background: true
+});
+
+// result contains output_file path
+const outputPath = result.output_file;
+```
+
+### Checking Background Agent Status
+
+```typescript
+// Read output file to check progress
+const output = await Read({ file_path: outputPath });
+
+// Parse for completion markers
+if (output.includes('[COMPLETE]')) {
+  // Agent finished
+}
+```
+
+## Production Patterns
+
+### Pattern 1: Parallel Exploration
+
+Launch multiple explore agents simultaneously:
+
+```typescript
+// Launch in single message for parallel execution
+const agents = await Promise.all([
+  Task({
+    description: "Search auth patterns",
+    prompt: "Find authentication implementations...",
+    subagent_type: "Explore",
+    run_in_background: true
+  }),
+  Task({
+    description: "Search API endpoints",
+    prompt: "Find all API route definitions...",
+    subagent_type: "Explore",
+    run_in_background: true
+  }),
+  Task({
+    description: "Search test patterns",
+    prompt: "Find test file patterns...",
+    subagent_type: "Explore",
+    run_in_background: true
+  })
+]);
+```
+
+### Pattern 2: Build Monitoring
+
+```typescript
+// Launch build in background
+const build = await Task({
+  description: "Production build",
+  prompt: "Run npm run build and report any errors...",
+  subagent_type: "Bash",
+  run_in_background: true
+});
+
+// Periodically check status
+while (!buildComplete) {
+  await sleep(10000); // Check every 10 seconds
+  const status = await Read({ file_path: build.output_file });
+
+  if (status.includes('Build complete') || status.includes('error')) {
+    buildComplete = true;
+    break;
+  }
+}
+```
+
+### Pattern 3: Test Pipeline
+
+```typescript
+// Sequential testing with background execution
+async function runTestPipeline() {
+  // Phase 1: Unit tests
+  const unit = await Task({
+    description: "Unit tests",
+    prompt: "Run unit tests: npm run test:unit",
+    subagent_type: "Bash",
+    run_in_background: true
+  });
+
+  // Wait for unit tests
+  const unitResult = await waitForCompletion(unit.output_file);
+
+  if (!unitResult.success) {
+    return { phase: 'unit', ...unitResult };
+  }
+
+  // Phase 2: Integration tests
+  const integration = await Task({
+    description: "Integration tests",
+    prompt: "Run integration tests: npm run test:integration",
+    subagent_type: "Bash",
+    run_in_background: true
+  });
+
+  // ... continue pipeline
+}
+```
+
+### Pattern 4: Deployment Orchestration
+
+```typescript
+async function deployWithValidation() {
+  // Pre-deployment checks (parallel)
+  const [lintResult, testResult, buildResult] = await Promise.all([
+    runBackgroundTask("lint", "npm run lint"),
+    runBackgroundTask("test", "npm test"),
+    runBackgroundTask("build", "npm run build")
+  ]);
+
+  // Validate all passed
+  if (!allPassed([lintResult, testResult, buildResult])) {
+    return { success: false, stage: 'validation' };
+  }
+
+  // Deploy backend
+  const backend = await runBackgroundTask(
+    "backend deploy",
+    "railway up"
+  );
+
+  if (!backend.success) {
+    return { success: false, stage: 'backend' };
+  }
+
+  // Deploy frontend
+  const frontend = await runBackgroundTask(
+    "frontend deploy",
+    "wrangler pages deploy dist"
+  );
+
+  // Smoke tests
+  const smoke = await runBackgroundTask(
+    "smoke tests",
+    "npm run test:smoke"
+  );
+
+  return { success: smoke.success, stages: allStages };
+}
+```
+
+## Error Handling
+
+### Timeout Management
+
+```typescript
+async function waitForCompletion(outputFile, timeoutMs = 300000) {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    const output = await Read({ file_path: outputFile });
+
+    if (isComplete(output)) {
+      return parseResult(output);
+    }
+
+    if (hasError(output)) {
+      return { success: false, error: parseError(output) };
+    }
+
+    await sleep(5000);
+  }
+
+  return { success: false, error: 'Timeout' };
+}
+```
+
+### Graceful Degradation
+
+```typescript
+async function robustBackgroundTask(description, prompt) {
+  try {
+    const agent = await Task({
+      description,
+      prompt,
+      subagent_type: "Bash",
+      run_in_background: true
+    });
+
+    return await waitForCompletion(agent.output_file);
+  } catch (error) {
+    console.error(`Background task failed: ${description}`);
+    return { success: false, error: error.message };
+  }
+}
+```
+
+## Monitoring Dashboard
+
+Create a status display for multiple background agents:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                    Background Agent Status                    ║
+╠══════════════════════════════════════════════════════════════╣
+║ Agent              │ Status      │ Duration  │ Progress      ║
+╠══════════════════════════════════════════════════════════════╣
+║ Unit Tests         │ ✅ Complete  │ 1m 23s    │ 100%          ║
+║ Integration Tests  │ 🔄 Running   │ 2m 45s    │ 67%           ║
+║ E2E Tests          │ ⏳ Pending   │ --        │ --            ║
+║ Backend Deploy     │ ⏳ Pending   │ --        │ --            ║
+║ Frontend Deploy    │ ⏳ Pending   │ --        │ --            ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Best Practices
+
+1. **Always set timeouts** - Background agents can hang
+2. **Log progress markers** - Enable status checking
+3. **Handle failures gracefully** - Don't crash on agent failure
+4. **Clean up output files** - Remove temporary files after completion
+5. **Use appropriate agent types** - Match agent to task
+
+## Output File Format
+
+Background agent output files should include:
+
+```
+[START] 2026-01-30T10:00:00Z
+Task: Description here
+
+[PROGRESS] Step 1 complete
+[PROGRESS] Step 2 complete
+
+[RESULT]
+{
+  "success": true,
+  "details": "..."
+}
+
+[COMPLETE] 2026-01-30T10:05:00Z
+```
+
+---
+
+*Use this template for complex orchestration workflows*