@arthai/agents 1.0.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@arthai/agents",
+  "version": "1.0.0",
+  "description": "AI-powered development toolkit for Claude Code — agents, skills, and hooks",
+  "bin": {
+    "arthai": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "dist/plugins/",
+    "bundles/",
+    "agents/",
+    "skills/",
+    "hooks/",
+    "templates/",
+    "install.sh",
+    "compiler.sh",
+    "portable.manifest",
+    "hook-defs.json",
+    "VERSION",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "plugins",
+    "arthai"
+  ],
+  "author": "Arth AI",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ArthTech-AI/claude-agents"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/portable.manifest

@@ -0,0 +1,112 @@
+# portable.manifest — Source of truth for symlink-managed files
+#
+# Format: TYPE PATH
+# Lines starting with # are comments
+# Paths are relative to this repo root
+#
+# TYPE can be: agent, skill, skill-dir, hook, railway-skill-dir
+#
+# agent      → symlinked to .claude/agents/<filename>
+# skill      → symlinked to .claude/skills/<filename>
+# skill-dir  → symlinked to .claude/skills/<dirname>/
+# hook       → symlinked to .claude/hooks/<filename>
+# railway-skill-dir → symlinked to .claude/skills/<dirname>/ (only with --railway)
+
+# Portable agents (25)
+agent agents/architect.md
+agent agents/code-reviewer.md
+agent agents/design-studio-create.md
+agent agents/design-studio-critique.md
+agent agents/design-studio-think.md
+agent agents/explore-light.md
+agent agents/frontend.md
+agent agents/gtm-expert.md
+agent agents/ops.md
+agent agents/product-manager.md
+agent agents/python-backend.md
+agent agents/qa-baseline-updater.md
+agent agents/qa-challenger.md
+agent agents/qa-domain.md
+agent agents/qa-e2e.md
+agent agents/qa-test-promoter.md
+agent agents/qa.md
+agent agents/setup.md
+agent agents/sre.md
+agent agents/stakeholder-reporter.md
+agent agents/meeting-prep.md
+agent agents/content-strategist.md
+agent agents/user-researcher.md
+agent agents/competitive-analyst.md
+agent agents/ai-consultant.md
+
+# Portable skills (30)
+skill skills/explore.md
+skill-dir skills/arth
+skill-dir skills/autopilot
+skill-dir skills/ci-fix
+skill-dir skills/custom-domain
+skill-dir skills/discord-ops
+skill-dir skills/fix
+skill-dir skills/incident
+skill-dir skills/implement
+skill-dir skills/issue
+skill-dir skills/planning
+skill-dir skills/pr
+skill-dir skills/precheck
+skill-dir skills/qa
+skill-dir skills/qa-incident
+skill-dir skills/qa-learn
+skill-dir skills/restart
+skill-dir skills/review-pr
+skill-dir skills/calibrate
+skill-dir skills/scan
+skill-dir skills/sre
+skill-dir skills/setup
+skill-dir skills/sync
+skill-dir skills/onboard
+skill-dir skills/welcome
+skill-dir skills/share
+skill-dir skills/templates
+skill-dir skills/wizard
+skill-dir skills/consulting
+skill-dir skills/client-discovery
+skill-dir skills/opportunity-map
+skill-dir skills/pitch-generator
+skill-dir skills/roi-calculator
+skill-dir skills/market-research
+skill-dir skills/solution-architect
+skill-dir skills/deliverable-builder
+skill-dir skills/engagement-tracker
+
+# Portable hooks (13)
+hook hooks/ensure-client-dir.sh
+hook hooks/check-deliverable.sh
+hook hooks/session-summary.sh
+hook hooks/triage-router.sh
+hook hooks/sync-agents.sh
+hook hooks/session-bootstrap.sh
+hook hooks/pre-bash-guard.sh
+hook hooks/pre-task-context.sh
+hook hooks/pre-edit-guard.sh
+hook hooks/post-test-summary.sh
+hook hooks/post-edit-lint.sh
+hook hooks/post-deploy-health.sh
+hook hooks/post-diff-test-compare.sh
+hook hooks/post-git-state.sh
+hook hooks/post-merge-cleanup.sh
+
+# Railway skills (13) — installed with --railway flag
+railway-skill-dir skills/railway/central-station
+railway-skill-dir skills/railway/database
+railway-skill-dir skills/railway/deploy
+railway-skill-dir skills/railway/deployment
+railway-skill-dir skills/railway/domain
+railway-skill-dir skills/railway/environment
+railway-skill-dir skills/railway/metrics
+railway-skill-dir skills/railway/new
+railway-skill-dir skills/railway/projects
+railway-skill-dir skills/railway/railway-docs
+railway-skill-dir skills/railway/service
+railway-skill-dir skills/railway/status
+railway-skill-dir skills/railway/templates
+hook hooks/session-end.sh

package/skills/arth/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: arth
+description: "Manage Arth services (engine, dashboard, DB) and register projects. Usage: /arth [restart|add|status|fix]"
+user-invocable: true
+arguments: "<command>"
+---
+
+# Arth Operations Skill
+
+Manage the Arth AI Development Orchestrator — its services, projects, and common failure recovery.
+
+## Arth Architecture
+
+Arth runs 3 services locally:
+
+| Service | Port | Process | Purpose |
+|---------|------|---------|---------|
+| PostgreSQL | 5433 | Docker (`arth-db`) | Project data, sessions, scores |
+| Engine | — | Node MCP server | Auto-ingests session logs every 60s |
+| Dashboard | 3333 | Next.js dev server | Web UI at http://localhost:3333 |
+
+Config file: `~/.arth/config.json`
+PID file: `~/.arth/arth.pid`
+Toolkit: `~/.claude-agents/`
+
+## Commands
+
+### `/arth restart` — Full restart of all services
+
+This is the correct restart procedure. The key insight: `arth stop` only kills PIDs
+from its PID file. **Orphan processes from crashed sessions can squat on ports**,
+causing the dashboard to serve stale data or fail to start. Always kill by port first.
+
+```bash
+# Step 1: Stop arth (kills tracked PIDs)
+arth stop
+
+# Step 2: Kill ANY orphan processes on arth ports (critical — arth stop misses these)
+lsof -ti:3333 | xargs kill -9 2>/dev/null   # Dashboard port
+# Do NOT kill port 5433 — that's the Docker postgres container
+
+# Step 3: Verify ports are clear
+sleep 1
+lsof -i :3333 | grep LISTEN  # Should return nothing
+
+# Step 4: Verify Docker DB is running
+docker ps --filter "name=arth-db" --format '{{.Names}} {{.Status}}'
+# If not running:
+# cd ~/arth && docker compose up -d
+
+# Step 5: Start fresh
+arth start
+
+# Step 6: Verify all 3 services
+arth status
+```
+
+After restart, open http://localhost:3333 and verify all projects appear.
+
+### `/arth add` — Register a new project
+
+The correct and only way to register a project with Arth:
+
+```bash
+# Step 1: cd into the project root (must be a git repo)
+cd /path/to/project
+
+# Step 2: Install claude-agents toolkit first (if not already installed)
+# For a fresh/greenfield project:
+~/.claude-agents/install.sh --init .
+
+# For an existing project with .claude/ already set up:
+~/.claude-agents/install.sh .
+
+# Step 3: Register with Arth (this also re-syncs toolkit)
+arth add .
+
+# Step 4: Verify
+arth status
+```
+
+**What `arth add .` does:**
+1. Detects git remote from `.git/config`
+2. Creates `.arth.json` in the project root (config file with gates, tools, mode)
+3. Runs `install.sh` to sync toolkit symlinks
+4. Inserts project record into the Arth PostgreSQL database
+5. Project appears on dashboard after next page load
+
+**Common mistakes (do NOT do these):**
+- `arth init` — does not exist
+- `arth setup .` — different command (full one-shot setup including multi-engine translation)
+- `arth register` — does not exist
+- Running `arth add` without installing claude-agents toolkit first
+
+### `/arth status` — Check everything
+
+```bash
+arth status
+```
+
+Shows: DB status, engine status, dashboard status, all registered projects with health.
+
+### `/arth fix` — Diagnose and fix common issues
+
+Run these checks in order:
+
+**1. Dashboard shows wrong project count or stale data:**
+- Root cause: Orphan `next start` or `next dev` process on port 3333 from a previous session
+- Fix: `/arth restart` (the full procedure above)
+
+**2. Dashboard not accessible at localhost:3333:**
+```bash
+# Check if anything is listening
+lsof -i :3333 | grep LISTEN
+
+# If nothing: arth start
+# If something but not arth: kill it, then arth start
+lsof -ti:3333 | xargs kill -9 2>/dev/null
+arth start
+```
+
+**3. "Database not running" in arth status:**
+```bash
+docker ps --filter "name=arth-db"
+# If not running:
+cd ~/arth && docker compose up -d
+# Verify:
+docker exec arth-db psql -U arth -d arth_engine -c "SELECT count(*) FROM projects;"
+```
+
+**4. Project registered in CLI but not on dashboard:**
+```bash
+# Verify it's in the DB
+docker exec arth-db psql -U arth -d arth_engine -c "SELECT name, path FROM projects;"
+# If it's there, dashboard is serving stale data → /arth restart
+# If it's NOT there, re-register:
+cd /path/to/project && arth add .
+```
+
+**5. Engine not ingesting sessions:**
+```bash
+# Check engine process
+ps aux | grep 'mcp.*arth' | grep -v grep
+# If not running:
+arth stop && arth start
+```
+
+## Argument Patterns
+
+| User Input | Action |
+|-----------|--------|
+| `/arth restart` | Full restart with orphan cleanup |
+| `/arth add` | Register current project (must be in project dir) |
+| `/arth status` | Show all services and projects |
+| `/arth fix` | Diagnose and fix common issues |
+| `/arth` (no args) | Show status |
+
+## Key Facts
+
+- Engine is an MCP server (stdio), NOT an HTTP server despite the "port 3100" label
+- Dashboard runs in **dev mode** (`next dev`) for live data — NOT `next start`
+- Docker container `arth-db` runs PostgreSQL on port 5433 (not default 5432)
+- `arth stop` only kills PIDs it knows about — always kill by port for orphans
+- `.arth.json` in project root = project is configured for Arth
+- `arth add .` is idempotent — safe to re-run