@arthai/agents 1.0.5 → 1.0.7

package/README.md

@@ -2,6 +2,22 @@
 
 AI development toolkit for Claude Code — agents, skills, and hooks organized into installable bundles.
 
+## Quick Start
+
+```bash
+# 1. Activate your license (one time)
+npx @arthai/agents activate ARTH-XXXX-XXXX-XXXX-XXXX
+
+# 2. Install a bundle into your project
+npx @arthai/agents install forge .
+
+# 3. Open Claude Code — skills are ready
+/calibrate                  # auto-configure for your codebase
+/planning my-feature        # start building
+```
+
+Don't have a key? Contact us at arthai.dev/pricing
+
 ## Install
 
 ```bash
@@ -11,10 +27,10 @@ npx @arthai/agents install forge .
 # Install multiple bundles
 npx @arthai/agents install forge spark shield .
 
-# See all available bundles
+# See all available bundles (no license needed)
 npx @arthai/agents list
 
-# Show what's in a bundle
+# Show what's in a bundle (no license needed)
 npx @arthai/agents info forge
 ```
 
@@ -119,8 +135,22 @@ Note: hooks merged into `.claude/settings.json` need to be removed manually.
 /plugin install forge@arthai-marketplace
 ```
 
+## License Activation
+
+A license key is required to install bundles. Browse and explore bundles without a key using `list` and `info`.
+
+```bash
+# Activate (one time — saves key locally)
+npx @arthai/agents activate ARTH-XXXX-XXXX-XXXX-XXXX
+
+# Key is stored at ~/.arthai/license — all future installs use it automatically
+# You can also set ARTHAI_LICENSE_KEY env var (useful for CI/teams)
+```
+
+**Key precedence:** `ARTHAI_LICENSE_KEY` env var > `~/.arthai/license` file > `--key` flag
+
 ## Requirements
 
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
 - Node.js 18+
-- License key (format: `ARTH-XXXX-XXXX-XXXX-XXXX`)
+- License key (get one at arthai.dev/pricing)

package/VERSION

@@ -1 +1 @@
-1.0.5
+1.0.7

package/agents/troubleshooter.md

@@ -0,0 +1,132 @@
+---
+name: troubleshooter
+description: "Specialized debugging agent for when other agents get stuck. Performs root cause analysis using error context, knowledge base, git history, and CLAUDE.md. Produces structured diagnosis with confidence level and recommended fix."
+model: sonnet
+---
+
+# Troubleshooter Agent
+
+You are a specialized debugging agent. You are called when another agent or workflow
+has failed multiple times and needs expert diagnosis.
+
+## When You Are Spawned
+
+Another agent has hit a wall — they've tried 2-3 fixes and keep failing. Your job
+is to diagnose the root cause and provide a fix with confidence rating.
+
+## Your Process (follow in order)
+
+### 1. Understand the Problem (DO NOT SKIP)
+
+Read the error context provided in your spawn prompt. Extract:
+- **Exact error message** (not paraphrased)
+- **What was being attempted** (the goal, not just the command)
+- **What has already been tried** (and why each attempt failed)
+- **The file(s) involved**
+
+### 2. Consult Knowledge Base (BEFORE forming any hypothesis)
+
+Check these sources in order:
+
+```
+.claude/knowledge/qa-knowledge/         → past incidents with error signatures
+.claude/knowledge/shared/conventions.md → project-specific gotchas and rules
+.claude/knowledge/shared/patterns.md    → architecture patterns that may explain the error
+.claude/knowledge/agents/               → per-agent learning files
+CLAUDE.md                               → project configuration, test commands, services
+```
+
+Search for:
+- The exact error message (or key phrases)
+- The file/module involved
+- The command that failed
+- Similar past incidents
+
+**If you find a match:** Follow the documented fix. Do not reinvent.
+**If no match:** Proceed to step 3.
+
+### 3. Gather Fresh Evidence
+
+Read the actual source code around the error:
+- The file mentioned in the error (read 50+ lines of context, not just the error line)
+- Related files (imports, callers, configuration)
+- Recent changes: `git log --oneline -10 -- <file>` and `git diff HEAD -- <file>`
+
+Check the environment:
+- `git status` — are there uncommitted changes that might cause the issue?
+- Check if the right dependencies are installed (node_modules, venv, etc.)
+- Check if services are running (ports, Docker containers)
+- Check environment variables that the code expects
+
+### 4. Form Hypothesis (evidence-based only)
+
+Based on steps 2-3, form ONE primary hypothesis and optionally one alternative.
+Each hypothesis MUST cite evidence:
+
+```
+HYPOTHESIS: [what I think is wrong]
+EVIDENCE:
+  - [source]: [what I found that supports this]
+  - [source]: [what I found that supports this]
+CONFIDENCE: HIGH / MEDIUM / LOW
+  - HIGH: evidence directly explains the error, fix is clear
+  - MEDIUM: evidence is consistent but not conclusive
+  - LOW: best guess based on limited evidence
+```
+
+### 5. Recommend Fix
+
+Provide a specific, actionable fix:
+
+```
+RECOMMENDED FIX:
+  File: [exact file path]
+  Change: [what to modify — be specific, not vague]
+  Why: [how this addresses the root cause]
+  Verify: [command to run to confirm the fix works]
+
+ALTERNATIVE FIX (if confidence < HIGH):
+  File: [exact file path]
+  Change: [what to modify]
+  Why: [different hypothesis this addresses]
+```
+
+### 6. Output Format
+
+Always produce this structured output:
+
+```markdown
+## Troubleshooter Diagnosis
+
+**Error:** [exact error]
+**Root Cause:** [1-2 sentence explanation]
+**Confidence:** HIGH / MEDIUM / LOW
+
+### Evidence
+- [source 1]: [finding]
+- [source 2]: [finding]
+- Knowledge base: [match found / no match]
+
+### Recommended Fix
+- File: [path]
+- Change: [specific change]
+- Verify: [command]
+
+### What Was Wrong With Previous Attempts
+- Attempt 1: [why it didn't work — specific reason]
+- Attempt 2: [why it didn't work — specific reason]
+
+### If This Doesn't Work
+- [Next diagnostic step to try]
+- [What data to gather]
+- [Whether to escalate to user — and what to ask them]
+```
+
+## Rules
+
+1. **Never guess.** Every claim must cite evidence from code, logs, KB, or git history.
+2. **Check KB first.** If a past incident matches, use that fix. Don't reinvent.
+3. **Be specific.** "Check the config" is not a fix. "Change line 42 of config.ts from X to Y" is.
+4. **Explain why previous attempts failed.** This is as valuable as the fix itself.
+5. **Know when to escalate.** If confidence is LOW and you can't gather more evidence, say so. Recommend what data to ask the user for.
+6. **Don't try the fix yourself.** Your job is diagnosis. The calling agent implements the fix.

package/bin/cli.js

@@ -13,10 +13,25 @@ const BUNDLES_DIR = path.join(TOOLKIT_DIR, 'bundles');
 const PLUGINS_DIR = path.join(TOOLKIT_DIR, 'dist', 'plugins');
 const INSTALL_SH = path.join(TOOLKIT_DIR, 'install.sh');
 
+const WORKER_URL = 'https://license-worker.muddassar-shaikh.workers.dev';
+const KEY_PATTERN = /^ARTH-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/;
+const ARTHAI_DIR = path.join(process.env.HOME || '~', '.arthai');
+const LICENSE_FILE_ARTHAI = path.join(ARTHAI_DIR, 'license');
+const LICENSE_FILE_AGENTS = path.join(process.env.HOME || '~', '.claude-agents', '.license');
+const VALIDATION_CACHE_FILE = path.join(ARTHAI_DIR, 'validation-cache');
+const VALIDATION_CACHE_TTL = 86400; // 24 hours in seconds
+const MANAGED_BLOCK_START = '<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->';
+const MANAGED_BLOCK_END   = '<!-- <<< claude-agents toolkit <<< -->';
+const GITIGNORE_BLOCK_START = '# >>> claude-agents managed (DO NOT EDIT THIS BLOCK) >>>';
+const GITIGNORE_BLOCK_END   = '# <<< claude-agents managed <<<';
+
 const args = process.argv.slice(2);
 const command = args[0];
 
 switch (command) {
+  case 'activate':
+    handleActivate(args[1]);
+    break;
   case 'install':
     handleInstall(args.slice(1));
     break;
@@ -88,6 +103,24 @@ function handleInstall(rawArgs) {
     process.exit(1);
   }
 
+  // License gate — must validate before any installation
+  const licenseKey = readLicenseKey(rawArgs);
+  if (!licenseKey) {
+    console.error('License required. Run: npx @arthai/agents activate ARTH-XXXX-XXXX-XXXX-XXXX');
+    console.error('Get a license at arthai.dev/pricing');
+    process.exit(1);
+  }
+  const licenseResult = validateWithWorker(licenseKey);
+  if (!licenseResult.valid) {
+    if (licenseResult.networkError) {
+      console.error('License server unavailable. Cannot install without a validated license.');
+      console.error('Check your internet connection and try again.');
+    } else {
+      console.error('Invalid license key. Check your key or get one at arthai.dev/pricing');
+    }
+    process.exit(1);
+  }
+
   // Resolve dependencies (topological order)
   const resolved = resolveDependencies(bundleNames);
   console.log(`Installing: ${resolved.join(' → ')}`);
@@ -123,6 +156,9 @@ function handleInstall(rawArgs) {
     totalHooks += counts.hooks;
   }
 
+  // Post-install project setup (parity with install.sh)
+  setupProjectClaude(targetDir);
+
   console.log(`\nDone. ${resolved.length} bundle(s) installed: ${totalCommands} skills, ${totalAgents} agents, ${totalHooks} hooks`);
 }
 
@@ -211,6 +247,181 @@ function handleLegacy(legacyArgs) {
   process.exit(result.status || 0);
 }
 
+// ── activate ──────────────────────────────────────────────────────────────────
+
+function handleActivate(key) {
+  if (!key) {
+    console.error('Usage: arthai activate <ARTH-XXXX-XXXX-XXXX-XXXX>');
+    process.exit(1);
+  }
+
+  if (!KEY_PATTERN.test(key)) {
+    console.error(`Invalid key format: "${key}"`);
+    console.error('Keys must be in the format ARTH-XXXX-XXXX-XXXX-XXXX (uppercase letters and digits)');
+    process.exit(1);
+  }
+
+  const machineId = computeMachineId();
+  const result = postToWorker('/activate', { key, machine_id: machineId });
+
+  if (result.networkError) {
+    console.error('Activation failed: License server unavailable.');
+    console.error('Check your internet connection and try again.');
+    process.exit(1);
+  }
+
+  if (!result.valid) {
+    const reason = result.reason === 'revoked'
+      ? 'This license key has been revoked.'
+      : 'Invalid license key. Check your key or get one at arthai.dev/pricing';
+    console.error(`Activation failed: ${reason}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(ARTHAI_DIR, { recursive: true });
+  fs.writeFileSync(LICENSE_FILE_ARTHAI, key + '\n', { mode: 0o600 });
+
+  // Store validation cache immediately so first install doesn't re-validate
+  writeValidationCache(key);
+
+  console.log(`License activated (org: ${result.org}, tier: ${result.tier})`);
+  console.log(`Key stored at: ${LICENSE_FILE_ARTHAI}`);
+}
+
+// ── license helpers ───────────────────────────────────────────────────────────
+
+// Read license key in precedence order:
+// 1. ARTHAI_LICENSE_KEY env var
+// 2. ~/.claude-agents/.license (existing clone-install path)
+// 3. ~/.arthai/license (npm activate path)
+// 4. --key flag in args
+function readLicenseKey(rawArgs) {
+  if (process.env.ARTHAI_LICENSE_KEY) {
+    return process.env.ARTHAI_LICENSE_KEY.trim() || null;
+  }
+
+  if (fs.existsSync(LICENSE_FILE_AGENTS)) {
+    const key = fs.readFileSync(LICENSE_FILE_AGENTS, 'utf8').trim();
+    if (key) return key;
+  }
+
+  if (fs.existsSync(LICENSE_FILE_ARTHAI)) {
+    const key = fs.readFileSync(LICENSE_FILE_ARTHAI, 'utf8').trim();
+    if (key) return key;
+  }
+
+  if (Array.isArray(rawArgs)) {
+    const flagIdx = rawArgs.indexOf('--key');
+    if (flagIdx !== -1 && rawArgs[flagIdx + 1]) {
+      return rawArgs[flagIdx + 1].trim() || null;
+    }
+  }
+
+  return null;
+}
+
+// POST to Worker synchronously using curl via stdin (payload not visible in process list).
+// Returns { valid, org, tier, reason, networkError } — never throws.
+function postToWorker(endpoint, body) {
+  try {
+    const payload = JSON.stringify(body);
+    const result = spawnSync(
+      'curl',
+      [
+        '--silent',
+        '--max-time', '10',
+        '--connect-timeout', '5',
+        '--fail-with-body',
+        '--request', 'POST',
+        '--header', 'Content-Type: application/json',
+        '--data', '@-',          // read payload from stdin, not command line
+        WORKER_URL + endpoint,
+      ],
+      {
+        input: payload,          // passed as stdin — not visible in ps/proc
+        timeout: 12000,
+      }
+    );
+
+    if (result.status !== 0 || result.error) {
+      return { valid: false, networkError: true };
+    }
+
+    const stdout = result.stdout.toString().trim();
+    if (!stdout) return { valid: false, networkError: true };
+
+    const json = JSON.parse(stdout);
+    return { ...json, networkError: false };
+  } catch (e) {
+    return { valid: false, networkError: true };
+  }
+}
+
+// Validate with Worker, using 24h cache for subsequent calls.
+// First call (no cache): fail-closed — Worker must respond.
+function validateWithWorker(key) {
+  const cached = readValidationCache(key);
+  if (cached !== null) {
+    return { valid: cached, networkError: false };
+  }
+
+  const result = postToWorker('/validate', { key });
+
+  if (result.networkError) {
+    // No cache exists — fail closed for first install
+    return { valid: false, networkError: true };
+  }
+
+  if (result.valid) {
+    writeValidationCache(key);
+  }
+
+  return result;
+}
+
+// Returns true/false if cache is fresh, null if cache is missing or expired.
+// Cache stores full SHA-256 key_hash (not plaintext, not truncated) to detect key changes.
+function readValidationCache(key) {
+  try {
+    if (!fs.existsSync(VALIDATION_CACHE_FILE)) return null;
+    const cache = JSON.parse(fs.readFileSync(VALIDATION_CACHE_FILE, 'utf8'));
+    const nowSec = Math.floor(Date.now() / 1000);
+    const { createHash } = require('crypto');
+    const keyHash = createHash('sha256').update(key).digest('hex');
+    if (cache.key_hash !== keyHash) return null;
+    // Reject future timestamps — prevents cache poisoning via pre-written cache files
+    if (typeof cache.timestamp !== 'number' || cache.timestamp > nowSec) return null;
+    if ((nowSec - cache.timestamp) >= VALIDATION_CACHE_TTL) return null;
+    return cache.valid === true;
+  } catch (e) {
+    return null;
+  }
+}
+
+function writeValidationCache(key) {
+  try {
+    fs.mkdirSync(ARTHAI_DIR, { recursive: true });
+    const { createHash } = require('crypto');
+    // Full SHA-256 hash — not truncated, prevents brute-force of short hashes
+    const keyHash = createHash('sha256').update(key).digest('hex');
+    const cache = { key_hash: keyHash, valid: true, timestamp: Math.floor(Date.now() / 1000) };
+    fs.writeFileSync(VALIDATION_CACHE_FILE, JSON.stringify(cache) + '\n', { mode: 0o600 });
+  } catch (e) {
+    // Non-fatal — validation will just re-check next time
+  }
+}
+
+function computeMachineId() {
+  try {
+    const { createHash } = require('crypto');
+    const hostname = require('os').hostname();
+    const username = process.env.USER || process.env.USERNAME || '';
+    return createHash('sha256').update(hostname + username).digest('hex');
+  } catch (e) {
+    return 'unknown';
+  }
+}
+
 // ── uninstall ────────────────────────────────────────────────────────────────
 
 function handleUninstall(rawArgs) {
@@ -406,6 +617,90 @@ function installBundle(pluginDir, claudeDir, skillsDir, agentsDir, name) {
   return counts;
 }
 
+// ── project setup (M6 — parity with install.sh) ───────────────────────────────
+
+function setupProjectClaude(targetDir) {
+  const claudeDir = path.join(targetDir, '.claude');
+  const version = readVersion();
+
+  // 1. CLAUDE.md — create from template if missing, inject managed block if absent
+  const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
+  const templatePath = path.join(TOOLKIT_DIR, 'templates', 'CLAUDE.md.template');
+  const managedBlockPath = path.join(TOOLKIT_DIR, 'templates', 'CLAUDE.md.managed-block');
+
+  if (!fs.existsSync(claudeMdPath) && fs.existsSync(templatePath)) {
+    const projectName = path.basename(targetDir);
+    const content = fs.readFileSync(templatePath, 'utf8').replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+    fs.writeFileSync(claudeMdPath, content);
+    console.log('  Created CLAUDE.md from template');
+  }
+
+  if (fs.existsSync(claudeMdPath) && fs.existsSync(managedBlockPath)) {
+    injectOrUpdateManagedBlock(claudeMdPath, managedBlockPath, version);
+  }
+
+  // 2. .gitignore — inject toolkit marker block if missing
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  injectGitignoreBlock(gitignorePath);
+
+  // 3. .claude/.claude-agents.conf — record installed bundles for re-sync tracking
+  // (Only write if we've already created the .claude dir; it should exist by now)
+  if (fs.existsSync(claudeDir)) {
+    const confPath = path.join(claudeDir, '.claude-agents.conf');
+    if (!fs.existsSync(confPath)) {
+      fs.writeFileSync(confPath, `# claude-agents configuration\nversion=${version}\n`);
+    }
+  }
+}
+
+function injectOrUpdateManagedBlock(claudeMdPath, managedBlockPath, version) {
+  const existing = fs.readFileSync(claudeMdPath, 'utf8');
+  const blockContent = fs.readFileSync(managedBlockPath, 'utf8').trimEnd();
+
+  const newBlock = `${MANAGED_BLOCK_START}\n<!-- version: ${version} -->\n${blockContent}\n${MANAGED_BLOCK_END}`;
+
+  const startIdx = existing.indexOf(MANAGED_BLOCK_START);
+  const endIdx = existing.indexOf(MANAGED_BLOCK_END);
+
+  if (startIdx === -1) {
+    // Block missing — append it
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    fs.writeFileSync(claudeMdPath, existing + separator + newBlock + '\n');
+    console.log('  Injected toolkit managed block into CLAUDE.md');
+  } else if (startIdx !== -1 && endIdx !== -1) {
+    // Block exists — check if version is stale
+    const existingBlock = existing.slice(startIdx, endIdx + MANAGED_BLOCK_END.length);
+    const versionMatch = existingBlock.match(/<!-- version: ([^>]+) -->/);
+    const existingVersion = versionMatch ? versionMatch[1].trim() : null;
+    if (existingVersion !== version) {
+      const updated = existing.slice(0, startIdx) + newBlock + existing.slice(endIdx + MANAGED_BLOCK_END.length);
+      fs.writeFileSync(claudeMdPath, updated);
+      console.log(`  Updated toolkit managed block in CLAUDE.md (${existingVersion} → ${version})`);
+    }
+  }
+}
+
+function injectGitignoreBlock(gitignorePath) {
+  const lines = [
+    GITIGNORE_BLOCK_START,
+    '.claude/.toolkit-last-seen-sha',
+    '.claude/.toolkit-setup-done',
+    '.claude/.claude-agents.conf',
+    GITIGNORE_BLOCK_END,
+  ].join('\n');
+
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, lines + '\n');
+    return;
+  }
+
+  const existing = fs.readFileSync(gitignorePath, 'utf8');
+  if (existing.includes(GITIGNORE_BLOCK_START)) return; // Already present
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(gitignorePath, existing + separator + lines + '\n');
+}
+
 function copyDirRecursive(src, dest) {
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const srcPath = path.join(src, entry.name);
@@ -432,6 +727,7 @@ function printUsage() {
   console.log(`arthai v${version} — AI-powered development toolkit for Claude Code
 
 Usage:
+  arthai activate <key>                         Activate your license key
   arthai install <bundle> [bundle...] [path]   Install bundle(s) into a project
   arthai list                                   List available bundles
   arthai info <bundle>                          Show bundle details

package/bundles/canvas.json

@@ -11,6 +11,6 @@
   "skills": [
     "skills/planning"
   ],
-  "hooks": [],
+  "hooks": ["project-setup"],
   "dependencies": []
 }

package/bundles/compass.json

@@ -11,6 +11,6 @@
   "skills": [
     "skills/planning"
   ],
-  "hooks": [],
+  "hooks": ["project-setup"],
   "dependencies": []
 }

package/bundles/counsel.json

@@ -24,6 +24,7 @@
     "skills/templates"
   ],
   "hooks": [
+    "project-setup",
     "ensure-client-dir",
     "check-deliverable"
   ],

package/bundles/cruise.json

@@ -6,6 +6,6 @@
   "skills": [
     "skills/autopilot"
   ],
-  "hooks": [],
+  "hooks": ["project-setup"],
   "dependencies": ["forge", "scalpel", "sentinel"]
 }

package/bundles/forge.json

@@ -18,9 +18,20 @@
     "skills/precheck",
     "skills/review-pr"
   ],
+  "agents": [
+    "agents/architect.md",
+    "agents/product-manager.md",
+    "agents/python-backend.md",
+    "agents/frontend.md",
+    "agents/qa.md",
+    "agents/code-reviewer.md",
+    "agents/troubleshooter.md"
+  ],
   "hooks": [
+    "project-setup",
     "triage-router",
-    "post-test-summary"
+    "post-test-summary",
+    "escalation-guard"
   ],
   "dependencies": []
 }

package/bundles/prism.json

@@ -16,6 +16,7 @@
     "skills/qa-incident"
   ],
   "hooks": [
+    "project-setup",
     "post-test-summary",
     "post-diff-test-compare"
   ],

package/bundles/scalpel.json

@@ -3,7 +3,8 @@
   "description": "Surgical bug fixing — targeted fixes, CI repair, issue triage",
   "version": "1.0.0",
   "agents": [
-    "agents/code-reviewer.md"
+    "agents/code-reviewer.md",
+    "agents/troubleshooter.md"
   ],
   "skills": [
     "skills/fix",
@@ -11,7 +12,9 @@
     "skills/issue"
   ],
   "hooks": [
-    "pre-edit-guard"
+    "project-setup",
+    "pre-edit-guard",
+    "escalation-guard"
   ],
   "dependencies": []
 }

package/bundles/sentinel.json

@@ -4,7 +4,8 @@
   "version": "1.0.0",
   "agents": [
     "agents/sre.md",
-    "agents/ops.md"
+    "agents/ops.md",
+    "agents/troubleshooter.md"
   ],
   "skills": [
     "skills/sre",
@@ -12,8 +13,13 @@
     "skills/restart"
   ],
   "hooks": [
+    "project-setup",
     "post-deploy-health",
-    "post-git-state"
+    "post-git-state",
+    "pre-server-port-guard",
+    "post-config-change-restart-reminder",
+    "post-server-crash-watch",
+    "escalation-guard"
   ],
   "dependencies": []
 }

package/bundles/shield.json

@@ -5,6 +5,7 @@
   "agents": [],
   "skills": [],
   "hooks": [
+    "project-setup",
     "pre-bash-guard",
     "pre-edit-guard",
     "session-bootstrap",

package/bundles/spark.json

@@ -13,6 +13,7 @@
     "skills/setup"
   ],
   "hooks": [
+    "project-setup",
     "session-bootstrap"
   ],
   "dependencies": []