@arthai/agents 1.0.7 → 1.0.8

package/README.md

@@ -18,56 +18,103 @@ npx @arthai/agents install forge .
 
 Don't have a key? Contact us at arthai.dev/pricing
 
+## Explore Before Installing
+
+No license needed to browse:
+
+```bash
+# See all available bundles with descriptions
+npx @arthai/agents list
+
+# See what's inside a specific bundle (agents, skills, hooks)
+npx @arthai/agents info forge
+
+# See what's inside every bundle
+npx @arthai/agents info prime
+```
+
 ## Install
 
 ```bash
 # Install a bundle into your project
 npx @arthai/agents install forge .
 
-# Install multiple bundles
+# Install multiple bundles at once
 npx @arthai/agents install forge spark shield .
 
-# See all available bundles (no license needed)
-npx @arthai/agents list
+# Install everything
+npx @arthai/agents install prime .
+```
 
-# Show what's in a bundle (no license needed)
-npx @arthai/agents info forge
+### What gets installed
+
+When you install a bundle, these files are created in your project:
+
+```
+your-project/
+  .claude/
+    skills/          # slash commands (/planning, /implement, /qa, etc.)
+    agents/          # specialized AI agents (architect, backend, QA, etc.)
+    hooks/           # automation hooks (guardrails, deploy health, etc.)
+    settings.json    # hooks registered here
+  CLAUDE.md          # project context file (created if missing)
+  .gitignore         # updated with toolkit entries
 ```
 
+### How skills, agents, and hooks work
+
+| Component | What it is | How you use it | Example |
+|-----------|-----------|----------------|---------|
+| **Skills** | Slash commands with structured workflows | Type `/skillname` in Claude Code | `/planning my-feature` — spawns PM + Architect + DA for adversarial planning |
+| **Agents** | Specialized AI personas with domain expertise | Skills spawn them automatically, or use Agent tool directly | `architect` — designs systems, `backend` — writes backend code, `qa` — validates |
+| **Hooks** | Shell scripts that fire on events | Automatic — run on session start, before/after commands | `pre-bash-guard` — blocks dangerous commands, `escalation-guard` — circuit breaker on 3 failures |
+
+**Skills are what you interact with. Agents and hooks work behind the scenes.**
+
 ## Bundles
 
 Pick what you need. Each bundle is a self-contained set of agents, skills, and hooks.
 
 ### Development
 
-| Bundle | Command | What you get |
-|--------|---------|-------------|
-| **forge** | `npx @arthai/agents install forge .` | Full dev workflow: `/planning`, `/implement`, `/qa`, `/pr`, `/precheck`, `/review-pr` + 6 agents (architect, PM, backend, frontend, QA, code-reviewer) + triage router hook |
-| **scalpel** | `npx @arthai/agents install scalpel .` | Bug fixing: `/fix`, `/ci-fix`, `/issue` + code-reviewer agent + edit guard hook |
-| **spark** | `npx @arthai/agents install spark .` | Project setup: `/onboard`, `/calibrate`, `/scan`, `/setup` + setup and explore agents |
+| Bundle | What you get |
+|--------|-------------|
+| **forge** | Full dev workflow: `/planning`, `/implement`, `/qa`, `/pr`, `/precheck`, `/review-pr` + architect, PM, backend, frontend, QA, code-reviewer agents + triage router + escalation guard |
+| **scalpel** | Bug fixing: `/fix`, `/ci-fix`, `/issue` + code-reviewer + troubleshooter agents |
+| **spark** | Project setup: `/onboard`, `/calibrate`, `/scan`, `/setup` + setup and explore agents |
 
 ### Operations
 
-| Bundle | Command | What you get |
-|--------|---------|-------------|
-| **sentinel** | `npx @arthai/agents install sentinel .` | SRE + ops: `/sre`, `/incident`, `/restart` + SRE and ops agents + deploy health + git state hooks |
-| **prism** | `npx @arthai/agents install prism .` | Deep QA: `/qa`, `/qa-learn`, `/qa-incident` + 6 QA agents (qa, e2e, domain, challenger, baseline, promoter) |
-| **shield** | `npx @arthai/agents install shield .` | Safety guardrails: bash guard, edit guard, session bootstrap, triage router hooks (no skills — hooks only) |
+| Bundle | What you get |
+|--------|-------------|
+| **sentinel** | SRE + ops: `/sre`, `/incident`, `/restart` + SRE, ops agents + deploy health, port guard, crash watcher hooks |
+| **prism** | Deep QA: `/qa`, `/qa-learn`, `/qa-incident` + 6 QA agents (qa, e2e, domain, challenger, baseline, promoter) |
+| **shield** | Safety guardrails only: bash guard, edit guard, session bootstrap, triage router, escalation guard (no skills — hooks only) |
 
 ### Strategy
 
-| Bundle | Command | What you get |
-|--------|---------|-------------|
-| **canvas** | `npx @arthai/agents install canvas .` | Design: `/planning` + design-studio agents (think, create, critique) + frontend agent |
-| **compass** | `npx @arthai/agents install compass .` | Product: `/planning` + PM, GTM, user researcher, content strategist agents |
-| **counsel** | `npx @arthai/agents install counsel .` | Consulting: 13 skills (client-discovery, proposals, deliverables, ROI, etc.) + 4 consulting agents |
+| Bundle | What you get |
+|--------|-------------|
+| **canvas** | Design: `/planning` + design-studio agents (think, create, critique) + frontend agent |
+| **compass** | Product: `/planning` + PM, GTM, user researcher, content strategist agents |
+| **counsel** | Consulting: 13 skills (client-discovery, proposals, deliverables, ROI, etc.) + 4 consulting agents |
 
 ### Power
 
-| Bundle | Command | What you get |
-|--------|---------|-------------|
-| **cruise** | `npx @arthai/agents install cruise .` | Autonomous mode: `/autopilot` — picks up issues, implements, QAs, creates PRs. Auto-installs forge + scalpel + sentinel. |
-| **prime** | `npx @arthai/agents install prime .` | Everything. All 25 agents, 37 skills, 16 hooks. |
+| Bundle | What you get |
+|--------|-------------|
+| **cruise** | Autonomous mode: `/autopilot` — picks up issues, implements, QAs, creates PRs. Auto-installs forge + scalpel + sentinel. |
+| **prime** | Everything. All agents, skills, and hooks. |
+
+### Which bundle should I start with?
+
+| You want to... | Install |
+|----------------|---------|
+| Build features end-to-end | `forge` |
+| Fix bugs with formal pipeline | `scalpel` |
+| Get set up on a new project | `spark` |
+| All of the above | `forge spark scalpel` |
+| Everything including SRE, QA, design, consulting | `prime` |
 
 ## Workflows
 
@@ -96,7 +143,7 @@ After installing, use skills in Claude Code:
 
 **Autonomous mode:**
 ```
-/autopilot                  # picks up issues → implements → QAs → creates PRs
+/autopilot                  # picks up issues, implements, QAs, creates PRs
 ```
 
 **Operations:**
@@ -106,49 +153,94 @@ After installing, use skills in Claude Code:
 /restart                    # restart local dev servers
 ```
 
-## Uninstall
+## Updating
 
 ```bash
-npx @arthai/agents uninstall forge .
+# Update to latest version (re-run install with @latest)
+npx @arthai/agents@latest install forge .
 ```
 
-Remove everything:
+### When to update
+
+- **After a new release** — check the changelog or Discord #deployments
+- **When a skill isn't working as expected** — updates often fix edge cases
+- **After `npx` cache issues** — clear cache and reinstall:
 
 ```bash
-rm -rf .claude/skills .claude/agents .claude/hooks
+# Clear npx cache if you're getting stale versions
+rm -rf ~/.npm/_npx
+npx @arthai/agents@latest install forge .
 ```
 
-Note: hooks merged into `.claude/settings.json` need to be removed manually.
+### What happens on update
 
-## Troubleshooting
+- Skills, agents, and hooks are **overwritten** with the latest versions
+- Your `CLAUDE.md` is **never overwritten** — only the managed toolkit block is updated
+- Your `.claude/settings.json` hooks are **merged** — existing hooks are preserved
+- Your project-specific files (`.claude/project-profile.md`, `.claude/knowledge/`) are **never touched**
 
-| Problem | Fix |
-|---------|-----|
-| Skills not showing | Restart Claude Code in the project |
-| `/planning` says unknown skill | Verify files exist: `ls .claude/skills/planning/SKILL.md` |
-| Install says "not found in dist/" | Update: `npx @arthai/agents@latest install forge .` |
+## Uninstall
 
-## Also available as Claude Code plugin
+```bash
+# Remove a specific bundle
+npx @arthai/agents uninstall forge .
 
+# Remove everything
+rm -rf .claude/skills .claude/agents .claude/hooks
 ```
-/plugin marketplace add ArthTech-AI/arthai-marketplace
-/plugin install forge@arthai-marketplace
-```
+
+Note: hooks merged into `.claude/settings.json` need to be removed manually. Open the file and delete entries referencing `.claude/hooks/`.
 
 ## License Activation
 
-A license key is required to install bundles. Browse and explore bundles without a key using `list` and `info`.
+A license key is required to install bundles. Browsing (`list`, `info`) is free.
 
 ```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)
 ```
 
+**For CI/teams:** Set `ARTHAI_LICENSE_KEY` environment variable instead of activating per-machine.
+
 **Key precedence:** `ARTHAI_LICENSE_KEY` env var > `~/.arthai/license` file > `--key` flag
 
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Skills not showing in Claude Code | Restart Claude Code in the project directory |
+| `/planning` says unknown skill | Verify: `ls .claude/skills/planning/SKILL.md` |
+| Install crashes on CLAUDE.md setup | Update: `rm -rf ~/.npm/_npx && npx @arthai/agents@latest install forge .` |
+| "License required" after activation | Check: `cat ~/.arthai/license` — should contain your key |
+| "License server unavailable" | Check internet connection. Try again in a minute. |
+| Old version stuck | Clear cache: `rm -rf ~/.npm/_npx` then reinstall |
+| Hooks not firing | Check `.claude/settings.json` has hook entries. Restart Claude Code. |
+
+## Best Practices
+
+1. **Start with `forge`** — it covers 80% of workflows. Add other bundles as needed.
+2. **Run `/calibrate` after install** — this teaches the toolkit your project's patterns, stack, and conventions. Without it, agents work generically.
+3. **Run `/onboard` every session** — quick briefing on open PRs, issues, and priorities.
+4. **Use `/precheck` before pushing** — catches CI failures locally in 30s instead of a 4-minute round-trip.
+5. **Don't edit files in `.claude/skills/` or `.claude/agents/`** — they get overwritten on update. Customize by adding your own files alongside them.
+6. **Keep `CLAUDE.md` up to date** — agents read it for project context. The more accurate it is, the better they perform.
+
+## Gotchas
+
+- **`npx` caches aggressively** — if you're not getting the latest version, run `rm -rf ~/.npm/_npx` before reinstalling
+- **Hooks stack, they don't replace** — installing a bundle twice adds duplicate hook entries to `settings.json`. Uninstall first if reinstalling.
+- **`CLAUDE.md` managed block is auto-updated** — the section between `<!-- >>> claude-agents toolkit -->` markers is overwritten on install. Don't put your content there.
+- **Agent teams require experimental flag** — set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your Claude Code settings (auto-configured by the installer)
+
+## Also available as Claude Code plugin
+
+```
+/plugin marketplace add ArthTech-AI/arthai-marketplace
+/plugin install forge@arthai-marketplace
+```
+
 ## Requirements
 
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)

package/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/bin/cli.js

@@ -489,6 +489,10 @@ function handleUninstall(rawArgs) {
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
+function looksLikePath(arg) {
+  return typeof arg === 'string' && (arg.includes(path.sep) || arg.startsWith('.') || arg.startsWith('~') || arg.startsWith('/'));
+}
+
 // Validate bundle names: only lowercase alphanumeric and hyphens, max 64 chars.
 // Prevents path traversal via names like "../../etc/passwd".
 function isValidBundleName(name) {

package/dist/plugins/canvas/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canvas",
   "description": "Design-driven development — adversarial design critique + frontend",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/canvas/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/compass/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "compass",
   "description": "Product strategy — PM, GTM, user research, content strategy",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/compass/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/counsel/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "counsel",
   "description": "AI consulting toolkit — client discovery, proposals, deliverables",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/counsel/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/cruise/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cruise",
   "description": "Autopilot mode — autonomous task execution (requires forge+scalpel+sentinel)",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/cruise/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/forge/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "forge",
   "description": "Full development workflow — plan, build, test, ship",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/forge/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/prime/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "prime",
   "description": "Everything — all agents, skills, and hooks in one plugin",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/prime/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/prism/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "prism",
   "description": "Deep QA — multi-agent testing, baseline tracking, incident analysis",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/prism/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/scalpel/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "scalpel",
   "description": "Surgical bug fixing — targeted fixes, CI repair, issue triage",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/scalpel/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/sentinel/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sentinel",
   "description": "Operations and reliability — SRE, incidents, deploy monitoring",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/sentinel/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/shield/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shield",
   "description": "Safety guardrails — bash guards, edit protection, session bootstrap",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/shield/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/dist/plugins/spark/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spark",
   "description": "Project setup and onboarding — calibrate, scan, bootstrap",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/spark/VERSION

@@ -1 +1 @@
-1.0.7
+1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arthai/agents",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "AI-powered development toolkit for Claude Code — agents, skills, and hooks",
   "bin": {
     "arthai": "bin/cli.js"