@arthai/agents 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# Claude Agents
+
+A portable toolkit of 18 AI agents, 18 skills, and 13 hooks for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Install once at `~/.claude-agents/`, symlink into any project — all projects stay in sync automatically.
+
+## Quick Start
+
+```bash
+# 1. Clone + license
+git clone git@github.com:ArthTech-AI/claude-agents.git ~/.claude-agents
+~/.claude-agents/install.sh --key ARTH-XXXX-XXXX-XXXX-XXXX
+
+# 2. Install into your project
+~/.claude-agents/install.sh /path/to/project
+```
+
+Open Claude Code — agents, skills, and hooks are active. Auto-syncs on every session start.
+
+First session: type `/calibrate` to deep-learn your project (reads source code, recommends agents, skills, MCP servers).
+
+### Other Install Modes
+
+| Command | When to use |
+|---------|-------------|
+| `install.sh --assess .` | See what you have vs the toolkit (read-only) |
+| `install.sh --setup .` | Change category selections |
+| `install.sh --upgrade .` | Upgrade existing project (converts stale files) |
+| `install.sh --convert .` | Migrate from copy-based install |
+| `install.sh --status .` | Show what's linked/overridden/missing |
+
+## What You Get
+
+**18 Agents** — specialized AI workers Claude delegates to automatically:
+
+| Tier | Model | Cost | Agents |
+|------|-------|------|--------|
+| Cheap | Haiku | 1x | explore-light, ops, qa-baseline-updater, qa-test-promoter |
+| Mid | Sonnet | 10x | frontend, python-backend, sre, qa, qa-domain, qa-e2e, qa-challenger, code-reviewer, design-studio:think, design-studio:critique |
+| Expensive | Opus | 60x | architect, product-manager, gtm-expert, design-studio:create |
+
+**19 Skills** — invoke with `/name` in Claude Code:
+
+| Skill | What it does |
+|-------|-------------|
+| `/calibrate` | Deep-learn project, recommend + install MCP servers, agents, skills, workflows, knowledge base |
+| `/onboard` | Session start — project briefing + work prioritization |
+| `/planning <feature>` | Spawn planning team (PM + Architect + optional Design/GTM) |
+| `/implement <feature>` | Spawn implementation team from plan |
+| `/pr` | QA + PR creation + post-merge cleanup |
+| `/qa [full\|staging\|prod]` | Run QA checks at different levels |
+| `/ci-fix [ci\|staging\|prod]` | Auto-remediate CI/CD failures (3 retries) |
+| `/issue <title>` | GitHub issue management |
+| `/explore <query>` | Fast codebase search (Haiku) |
+| `/scan` | Auto-populate CLAUDE.md from codebase |
+| `/sync` | Sync toolkit, check status, contribute back |
+| `/restart` | Kill and restart local dev servers |
+| `/sre <cmd>` | SRE operations: status, health, logs, debug |
+| `/qa-incident` | Log a QA incident |
+| `/qa-learn` | Review QA knowledge base |
+| `/discord-ops` | Discord ChatOps reference |
+| `/superpowers` | Advanced operations |
+| `/autopilot [issue]` | Autonomous work loop — assess, plan, implement, QA, PR |
+| `/railway` | Railway-specific ops (needs `--railway` flag) |
+
+**13 Hooks** — run automatically on Claude Code events:
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| triage-router.sh | UserPromptSubmit | Cost-aware routing to cheaper agents |
+| session-bootstrap.sh | SessionStart | Compact project briefing |
+| sync-agents.sh | SessionStart | Auto-pull repo + re-sync |
+| pre-bash-guard.sh | PreToolUse | Blocks dangerous commands |
+| pre-edit-guard.sh | PreToolUse | Prevents edits to protected files |
+| pre-task-context.sh | PreToolUse | Injects CLAUDE.md into spawned agents |
+| post-test-summary.sh | PostToolUse | Summarizes test/lint output |
+| post-deploy-health.sh | PostToolUse | Health checks after deploys |
+| post-edit-lint.sh | PostToolUse | Lint check after file edits |
+| sync-worktree.sh | PostToolUse | Syncs config across worktrees |
+| sync-railway-worktree.sh | PostToolUse | Railway worktree sync |
+| post-git-state.sh | PostToolUse | Detects merges, resets autopilot phase |
+| session-start.sh | SessionStart | Legacy session start |
+
+## Install Modes
+
+| Command | Purpose |
+|---------|---------|
+| `install.sh .` | Sync — create missing symlinks, skip existing files |
+| `install.sh --init .` | Greenfield — scaffold dirs + CLAUDE.md + settings.json + sync |
+| `install.sh --setup .` | Interactive — pick which categories to install |
+| `install.sh --convert .` | Migrate — replace matching copies with symlinks |
+| `install.sh --assess .` | Brownfield analysis — read-only, shows diffs |
+| `install.sh --upgrade .` | Brownfield upgrade — interactive per-file conversion |
+| `install.sh --status .` | Status report — what's linked, overridden, missing |
+| `install.sh --uninstall .` | Clean removal — restore backups, remove symlinks |
+| `install.sh --generate-config .` | Generate config from existing .claude/ contents |
+| `install.sh --key KEY` | Store license key |
+
+Flags: `--railway` (Railway skills), `--yes` (auto-approve upgrades), `--skip file1,file2` (exclude files)
+
+## How It Works
+
+Symlinks from your project to `~/.claude-agents/`. Update the repo, all projects update.
+
+```
+your-project/.claude/agents/architect.md  →  ~/.claude-agents/agents/architect.md
+```
+
+**Override**: Replace any symlink with a regular file. Installer skips it forever.
+**Auto-sync**: `sync-agents.sh` hook pulls latest on every session start.
+**Auto-adapt**: `/calibrate` reads actual source code (not just config files) to tailor agents, skills, MCP servers, and workflows to your project.
+**Cost routing**: Triage router delegates to Haiku/Sonnet before using Opus.
+
+## Docs
+
+- **[GETTING-STARTED.md](GETTING-STARTED.md)** — Full user guide (install, usage, customization, contributing)
+- **[tests/README.md](tests/README.md)** — Test suite quick start
+- **[tests/TESTING.md](tests/TESTING.md)** — Full test guide (suites, fixtures, libraries, writing tests)
+
+## Requirements
+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings
+- License key (format: `ARTH-XXXX-XXXX-XXXX-XXXX`)
+- (Optional) [Railway CLI](https://docs.railway.app/guides/cli) for Railway skills

package/VERSION

@@ -0,0 +1 @@
+1.0.0