@arthai/agents 1.0.4 → 1.0.6

package/skills/license/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: license
+description: "Manage license keys — issue, revoke, list, verify. Usage: /license <issue|revoke|list|verify> <args>"
+user-invocable: true
+arguments: "<issue|revoke|list|verify> <args>"
+---
+
+# /license — License Key Management
+
+Manage license keys for the claude-agents toolkit. Issue keys to new users, revoke access, list active keys, verify a key works.
+
+## Prerequisites
+
+- Cloudflare wrangler authenticated (`npx wrangler whoami`)
+- KV namespace ID: `4ce2c105e0964b4789dcc717a3fb0464`
+- Worker URL: `https://license-worker.muddassar-shaikh.workers.dev`
+
+## Commands
+
+### `/license issue <org-name> [--tier indie|team|enterprise]`
+
+Generate a new license key and add it to Cloudflare KV.
+
+```bash
+# 1. Generate random key
+NEW_KEY="ARTH-$(openssl rand -hex 2 | tr 'a-f' 'A-F')-$(openssl rand -hex 2 | tr 'a-f' 'A-F')-$(openssl rand -hex 2 | tr 'a-f' 'A-F')-$(openssl rand -hex 2 | tr 'a-f' 'A-F')"
+
+# 2. Compute SHA-256 hash
+HASH=$(echo -n "$NEW_KEY" | shasum -a 256 | awk '{print $1}')
+
+# 3. Seed into KV
+npx wrangler kv key put \
+  --namespace-id="4ce2c105e0964b4789dcc717a3fb0464" \
+  "key:$NEW_KEY" \
+  "{\"hash\":\"$HASH\",\"org\":\"<org-name>\",\"tier\":\"<tier>\",\"status\":\"active\",\"issued_at\":\"$(date +%Y-%m-%d)\",\"activations\":[]}"
+
+# 4. Verify it works
+curl -s -X POST https://license-worker.muddassar-shaikh.workers.dev/validate \
+  -H "Content-Type: application/json" \
+  -d "{\"key\":\"$NEW_KEY\"}"
+# Should return: {"valid":true,"org":"<org-name>","tier":"<tier>"}
+
+# 5. (Optional) Add hash to authorized-keys.txt for clone-install users
+echo "# <org-name>" >> ~/.claude-agents/authorized-keys.txt
+echo "$HASH" >> ~/.claude-agents/authorized-keys.txt
+```
+
+**Output to give the customer:**
+```
+Your arthai license key: ARTH-XXXX-XXXX-XXXX-XXXX
+
+To activate:
+  npx @arthai/agents activate ARTH-XXXX-XXXX-XXXX-XXXX
+
+To install:
+  npx @arthai/agents install forge .
+
+Available bundles: forge, scalpel, spark, sentinel, prism, canvas, compass, prime
+```
+
+Default tier is `indie` if not specified.
+
+---
+
+### `/license revoke <key>`
+
+Disable a license key. Takes effect within 24h (cache TTL).
+
+```bash
+# 1. Remove from Cloudflare KV
+npx wrangler kv key delete \
+  --namespace-id="4ce2c105e0964b4789dcc717a3fb0464" \
+  "key:<ARTH-XXXX-XXXX-XXXX-XXXX>"
+
+# 2. Remove from authorized-keys.txt (if they're also a clone user)
+# Find their hash:
+HASH=$(echo -n "<ARTH-XXXX-XXXX-XXXX-XXXX>" | shasum -a 256 | awk '{print $1}')
+echo "Remove this hash from ~/.claude-agents/authorized-keys.txt: $HASH"
+# Then commit + push authorized-keys.txt
+
+# 3. Verify revocation
+curl -s -X POST https://license-worker.muddassar-shaikh.workers.dev/validate \
+  -H "Content-Type: application/json" \
+  -d "{\"key\":\"<ARTH-XXXX-XXXX-XXXX-XXXX>\"}"
+# Should return: {"valid":false,"reason":"invalid_key"}
+```
+
+**Two-surface revocation (BOTH required for full revocation):**
+1. KV deletion — blocks npm-path users immediately (next validation)
+2. authorized-keys.txt removal — blocks clone-install users (next git pull + session)
+
+---
+
+### `/license list`
+
+List all active license keys in KV.
+
+```bash
+npx wrangler kv key list --namespace-id="4ce2c105e0964b4789dcc717a3fb0464"
+```
+
+To see details for a specific key:
+```bash
+npx wrangler kv key get --namespace-id="4ce2c105e0964b4789dcc717a3fb0464" "key:<ARTH-XXXX-XXXX-XXXX-XXXX>"
+```
+
+---
+
+### `/license verify <key>`
+
+Check if a specific key is valid.
+
+```bash
+curl -s -X POST https://license-worker.muddassar-shaikh.workers.dev/validate \
+  -H "Content-Type: application/json" \
+  -d "{\"key\":\"<ARTH-XXXX-XXXX-XXXX-XXXX>\"}"
+```
+
+Returns:
+- Valid: `{"valid":true,"org":"name","tier":"indie"}`
+- Invalid: `{"valid":false,"reason":"invalid_key"}`
+
+---
+
+## Full User Lifecycle
+
+```
+NEW USER ONBOARDING:
+  1. User finds toolkit (npm, marketplace, docs)
+  2. User tries: npx @arthai/agents install forge .
+     → "License required. Get a key at arthai.dev/pricing"
+  3. User contacts you
+  4. You run: /license issue customer-name
+  5. You send them the key
+  6. User runs: npx @arthai/agents activate ARTH-XXXX-XXXX-XXXX-XXXX
+     → "License activated"
+  7. User runs: npx @arthai/agents install forge .
+     → Toolkit installed, all skills work
+
+KEY ROTATION:
+  1. /license issue customer-name    (new key)
+  2. Send new key to customer
+  3. Customer runs: npx @arthai/agents activate ARTH-NEW-KEY
+  4. /license revoke ARTH-OLD-KEY    (after grace period)
+
+REVOCATION:
+  1. /license revoke ARTH-XXXX-XXXX-XXXX-XXXX
+  2. Remove hash from authorized-keys.txt + commit + push
+  3. Within 24h: user's toolkit is disabled on next session
+```
+
+## Configuration
+
+| Setting | Value |
+|---------|-------|
+| KV Namespace ID | `4ce2c105e0964b4789dcc717a3fb0464` |
+| Worker URL | `https://license-worker.muddassar-shaikh.workers.dev` |
+| Cache TTL | 24 hours (revocation delay) |
+| Key format | `ARTH-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}` |

package/skills/planning/SKILL.md

@@ -60,7 +60,86 @@ Map user choices:
 
 Store the resolved mode as `DEBATE_MODE` (values: `lite`, `fast`, `full`).
 
-### 3. Codebase Scan
+### 3. Phase 0: Spec Generation (before debate)
+
+Before any debate rounds, the PM generates a **spec doc** that becomes the foundation for all subsequent work. This ensures user stories and edge cases are defined BEFORE architecture decisions.
+
+**Create the specs directory:**
+```bash
+mkdir -p .claude/specs
+```
+
+**Spawn PM agent (subagent_type="product-manager", model="sonnet") for spec generation only:**
+
+Prompt:
+```
+You are a Product Manager generating a spec doc for the feature "{feature-name}".
+
+Feature brief: {FEATURE_BRIEF}
+
+Generate a spec doc with these sections:
+
+## User Stories
+Write 3-7 user stories covering the happy path and key error states.
+Format: "As a [user type], I want [action], so that [outcome]"
+Each story must have:
+- **Story ID**: US-1, US-2, etc.
+- **Priority**: P0 (must-have for launch) or P1 (important but deferrable)
+- **Acceptance**: specific testable condition that proves this story is done
+
+Example:
+  US-1 [P0]: As a new developer, I want to install the toolkit with one command,
+  so that I can start using it without manual configuration.
+  Acceptance: `npx @arthai/agents install forge .` succeeds and skills are available.
+
+## User Journey
+Step-by-step flow from the user's first interaction to completion.
+Include:
+- **Happy path**: numbered steps (1. User does X → 2. System responds Y → ...)
+- **Decision points**: where the user makes a choice (mark with ◆)
+- **Error branches**: where things can go wrong (mark with ✗ and show recovery path)
+
+Format as a text flowchart:
+```
+1. User discovers feature
+2. User does [action]
+   ◆ Decision: [choice A] or [choice B]
+   → Choice A: proceed to step 3
+   → Choice B: proceed to step 5
+3. System responds with [result]
+   ✗ Error: [what went wrong] → Recovery: [how to fix]
+4. ...
+```
+
+## Edge Cases
+Structured list of what can go wrong. For each:
+- **ID**: EC-1, EC-2, etc.
+- **Scenario**: what triggers this edge case
+- **Expected behavior**: what should happen (not crash, not hang)
+- **Severity**: Critical (blocks user) / High (degrades experience) / Medium (inconvenience)
+- **Linked story**: which user story this edge case relates to
+
+## Success Criteria
+Measurable outcomes tied to user stories. These become the acceptance criteria
+that /implement and /qa use to validate the implementation.
+- Each criterion references a story ID
+- Each criterion is binary: pass or fail, no subjective judgment
+```
+
+**Write the output to `.claude/specs/{feature-name}.md`** with this frontmatter:
+
+```markdown
+---
+feature: {feature-name}
+generated: {ISO date}
+stories: {count}
+edge_cases: {count}
+---
+```
+
+**Store the spec content as `FEATURE_SPEC`** — this is injected into the shared context block for all debate participants.
+
+### 4. Codebase Scan
 
 Spawn an `explore-light` subagent (model: haiku) to scan for relevant files:
 
@@ -70,7 +149,7 @@ prompt: "For a feature called '{feature-name}', find: (1) related backend routes
 
 Store the result as `CODEBASE_CONTEXT`.
 
-### 4. Create Team + Tasks
+### 5. Create Team + Tasks
 
 Create team: `planning-{feature-name}`
 
@@ -78,12 +157,13 @@ Create these tasks:
 
 | Task | Owner | Subject |
 |------|-------|---------|
-| 1 | product-manager | Define product spec for {feature-name} |
+| 0 | product-manager | Generate spec doc for {feature-name} (Phase 0 — already done above) |
+| 1 | product-manager | Define product scope for {feature-name} (uses spec as input) |
 | 2 | architect | Design technical plan for {feature-name} |
 | 3 (if --design) | design-thinker | Create design brief for {feature-name} |
 | 4 (if not --lite) | devils-advocate | Challenge scope and feasibility for {feature-name} |
 
-### 5. Build Shared Context Block
+### 6. Build Shared Context Block
 
 Compose this block to inject into every teammate's spawn prompt:
 
@@ -97,6 +177,11 @@ Auth: {AUTH_APPROACH}
 ## Feature: {feature-name}
 {FEATURE_BRIEF}
 
+## Spec Doc (from Phase 0)
+{FEATURE_SPEC}
+
+(Full spec at: .claude/specs/{feature-name}.md)
+
 ## Relevant Codebase
 {CODEBASE_CONTEXT}
 
@@ -116,13 +201,13 @@ This planning session runs in {DEBATE_MODE} mode.
 - If DA recommends KILL and user overrides, record as USER OVERRIDE in the plan.
 ```
 
-### 6. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
+### 7. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
 
 Spawn all teammates in a **single message** with multiple Task tool calls:
 
 **Always spawn:**
 - **product-manager** (subagent_type="product-manager", model="opus")
-  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'.\n\nIn Round 1, you LEAD with your scope claim. Format your must-haves as:\n  [M1] requirement — BECAUSE reason\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver user value, is it over-engineered, what is the time-to-value?\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence."
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'. You generated the spec doc in Phase 0 — your user stories and edge cases are in the shared context above. Use them as the foundation for your scope claim.\n\nIn Round 1, you LEAD with your scope claim. Each must-have should trace to one or more user stories (reference by ID, e.g., 'US-1, US-3'). Format your must-haves as:\n  [M1] requirement — BECAUSE reason (traces to US-X)\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver the user journey as specified? Is it over-engineered? What is the time-to-value? Reference edge cases the approach doesn't handle.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Reference user stories to justify why a must-have cannot be cut."
 
 - **architect** (subagent_type="architect", model="opus")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the Architect. Own the 'how'.\n\nIn Round 1, you COUNTER the PM's scope from a feasibility lens. Challenge feasibility, flag hidden complexity, identify scope creep vectors, propose a counter-scope.\n\nIn Round 2, you LEAD with your technical approach: API contract, DB changes, architecture decision + WHY, task breakdown with S/M/L/XL estimates, implementation cost, dependencies, risks.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Keep it simple for early-stage. Push back on scope that doesn't match the development stage."
@@ -142,7 +227,7 @@ Spawn all teammates in a **single message** with multiple Task tool calls:
 - **gtm-expert** (subagent_type="gtm-expert", model="sonnet")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the GTM Expert. Own distribution and launch strategy. Advise on positioning, viral mechanics, and launch sequencing. Challenge the team on how users will discover and adopt this feature. Your output feeds into Round 3 as additional evidence for the devil's advocate."
 
-### 7. Structured Debate Protocol
+### 8. Structured Debate Protocol
 
 Facilitate the following rounds in sequence. Each phase completes before the next begins.
 
@@ -281,7 +366,7 @@ Each matched item is flagged as a RISK NOTE in the plan.
 
 ---
 
-### 8. Convergence Logic
+### 9. Convergence Logic
 
 **Plan is APPROVED when ALL of the following are true after all applicable rounds complete:**
 - Rounds 1 and 2 have zero UNRESOLVED items
@@ -298,7 +383,7 @@ If user overrides a KILL recommendation, record as `USER OVERRIDE` in the plan.
 
 In lite and fast modes, skip convergence checks for rounds that were not run. Apply only the checks applicable to completed rounds.
 
-### 9. Scope Lock
+### 10. Scope Lock
 
 After convergence, compute a `scope_hash`:
 - Concatenate all locked MUST-HAVE strings from Round 1 in order
@@ -307,7 +392,7 @@ After convergence, compute a `scope_hash`:
 
 When `/implement` loads the plan, it can verify the hash against the locked must-haves to detect tampering.
 
-### 10. Write Plan File + Present to User
+### 11. Write Plan File + Present to User
 
 Synthesize teammate outputs into a structured plan and **write it to `.claude/plans/{feature-name}.md`** using the Write tool. This file is read by `/implement` to auto-configure the implementation team.
 
@@ -319,6 +404,7 @@ feature: {feature-name}
 debate_mode: {DEBATE_MODE}
 scope_hash: {SHA-256 of locked must-haves}
 da_confidence: {HIGH|MEDIUM|LOW|N/A}
+spec: specs/{feature-name}.md
 layers:
   - frontend  # include if ANY frontend tasks exist
   - backend   # include if ANY backend tasks exist
@@ -326,6 +412,9 @@ layers:
 
 # Planning Summary: {feature-name}
 
+## Spec Reference
+See `.claude/specs/{feature-name}.md` for user stories, user journey, edge cases, and success criteria.
+
 ## Problem & User Segment (from PM)
 ...
 
@@ -396,7 +485,7 @@ layers:
 
 Present the plan to the user for review.
 
-### 11. Cleanup
+### 12. Cleanup
 
 After user reviews the plan:
 - Send shutdown_request to all teammates.

package/skills/publish/SKILL.md

@@ -216,3 +216,6 @@ Tell the user to test in Claude Code:
 | `marketplace.json not found` | File at repo root instead of `.claude-plugin/` | Move to `.claude-plugin/marketplace.json` |
 | `E403 cannot publish over previous version` | VERSION not bumped | Derive from git tag, not VERSION file |
 | `Plugin directory not found at path` | `source` path in marketplace.json is wrong | Must be `./plugins/<name>` relative to marketplace root |
+| Version defaults to 1.0.0 | `actions/checkout` uses shallow clone, tags not fetched | Add `fetch-depth: 0` and `fetch-tags: true` to checkout step |
+| Skills not showing in Claude Code | Skills in `skills/` not `commands/` | User-invocable skills must be in `commands/` as flat .md files |
+| npx install doesn't register | Files in `.claude/plugins/` not discovered | npx should copy to `.claude/skills/` + `.claude/agents/`, not `.claude/plugins/` |

package/skills/qa-incident/SKILL.md

@@ -42,6 +42,60 @@ affected_files:
 
 4. **Confirm to user**: "Incident logged. Next `/qa` run will generate a regression test targeting this issue."
 
+## Auto-Logging from Escalation (Circuit Breaker Resolution)
+
+When an agent resolves a stuck situation (circuit breaker was tripped, then the issue was fixed),
+the resolution should be logged automatically. This enables future agents to find the fix
+without repeating the same debugging journey.
+
+**Trigger:** Any workflow that resolves an error after the escalation guard tripped (3+ consecutive failures).
+
+**Auto-log format** — create `.claude/qa-knowledge/incidents/{date}-escalation-{slug}.md`:
+
+```markdown
+---
+date: {today YYYY-MM-DD}
+severity: medium
+status: covered
+type: escalation-resolution
+error_signature: {from .claude/.escalation-state.json}
+affected_files:
+  - {files that were modified to fix the issue}
+---
+# Escalation: {brief description of what was stuck}
+
+## Error
+{exact error message that triggered the circuit breaker}
+
+## What Was Tried (failed)
+1. {attempt 1 from escalation state} → {result}
+2. {attempt 2} → {result}
+3. {attempt 3} → {result}
+
+## Root Cause
+{what was actually wrong}
+
+## Fix Applied
+{what change resolved the issue}
+
+## How to Prevent
+{if applicable — what convention or check would catch this earlier}
+
+## Search Keywords
+{error message fragments, file names, command patterns — for future KB searches}
+```
+
+**Also update** `.claude/qa-knowledge/bug-patterns.md` if this represents a new pattern:
+```
+## {Pattern name}
+- **Signature:** {error message or command pattern}
+- **Root cause:** {common reason}
+- **Fix:** {standard resolution}
+- **First seen:** {date}
+```
+
+This closes the learning loop: stuck → escalate → fix → log → future agents find it instantly.
+
 ## If No Description Provided
 
 Ask: "Describe the issue you want to log (e.g., 'admin page crashes when user has no sessions')"