@arthai/agents 1.0.0

package/skills/railway/projects/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: projects
+description: This skill should be used when the user wants to list all projects, switch projects, rename a project, enable/disable PR deploys, make a project public/private, or modify project settings.
+allowed-tools: Bash(railway:*)
+---
+
+# Project Management
+
+List, switch, and configure Railway projects.
+
+## When to Use
+
+- User asks "show me all my projects" or "what projects do I have"
+- User asks about projects across workspaces
+- User asks "what workspaces do I have"
+- User wants to switch to a different project
+- User asks to rename a project
+- User wants to enable/disable PR deploys
+- User wants to make a project public or private
+- User asks about project settings
+
+## List Projects
+
+The `railway list --json` output can be very large. Run in a subagent and return only essential fields:
+
+- Project: `id`, `name`
+- Workspace: `id`, `name`
+- Services: `name` (optional, if user needs service context)
+
+```bash
+railway list --json
+```
+
+Extract and return a simplified summary, not the full JSON.
+
+## List Workspaces
+
+```bash
+railway whoami --json
+```
+
+Returns user info including all workspaces the user belongs to.
+
+## Switch Project
+
+Link a different project to the current directory:
+
+```bash
+railway link -p <project-id-or-name>
+```
+
+Or interactively:
+
+```bash
+railway link
+```
+
+After switching, use `status` skill to see project details.
+
+## Update Project
+
+Modify project settings via GraphQL API.
+
+### Get Project ID
+
+```bash
+railway status --json
+```
+
+Extract `project.id` from the response.
+
+### Update Mutation
+
+```bash
+bash <<'SCRIPT'
+scripts/railway-api.sh \
+  'mutation updateProject($id: String!, $input: ProjectUpdateInput!) {
+    projectUpdate(id: $id, input: $input) { name prDeploys isPublic botPrEnvironments }
+  }' \
+  '{"id": "PROJECT_ID", "input": {"name": "new-name"}}'
+SCRIPT
+```
+
+### ProjectUpdateInput Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | String | Project name |
+| `description` | String | Project description |
+| `isPublic` | Boolean | Make project public/private |
+| `prDeploys` | Boolean | Enable/disable PR deploys |
+| `botPrEnvironments` | Boolean | Enable Dependabot/Renovate PR environments |
+
+### Examples
+
+**Rename project:**
+```bash
+scripts/railway-api.sh '<mutation>' '{"id": "uuid", "input": {"name": "new-name"}}'
+```
+
+**Enable PR deploys:**
+```bash
+scripts/railway-api.sh '<mutation>' '{"id": "uuid", "input": {"prDeploys": true}}'
+```
+
+**Make project public:**
+```bash
+scripts/railway-api.sh '<mutation>' '{"id": "uuid", "input": {"isPublic": true}}'
+```
+
+**Multiple fields:**
+```bash
+scripts/railway-api.sh '<mutation>' '{"id": "uuid", "input": {"name": "new-name", "prDeploys": true}}'
+```
+
+## Composability
+
+- **View project details**: Use `status` skill
+- **Create new project**: Use `new` skill
+- **Manage environments**: Use `environment` skill
+
+## Error Handling
+
+### Not Authenticated
+```
+Not authenticated. Run `railway login` first.
+```
+
+### No Projects
+```
+No projects found. Create one with `railway init`.
+```
+
+### Permission Denied
+```
+You don't have permission to modify this project. Check your Railway role.
+```
+
+### Project Not Found
+```
+Project "foo" not found. Run `railway list` to see available projects.
+```

package/skills/railway/projects/references/environment-config.md

@@ -0,0 +1,183 @@
+# Environment Config Reference
+
+The `EnvironmentConfig` object is used to configure services, volumes, and shared variables in Railway.
+
+## Structure
+
+```json
+{
+  "services": {
+    "<serviceId>": {
+      "source": { ... },
+      "build": { ... },
+      "deploy": { ... },
+      "variables": { ... },
+      "networking": { ... }
+    }
+  },
+  "sharedVariables": { ... },
+  "volumes": { ... },
+  "buckets": { ... }
+}
+```
+
+Only include fields being changed. The patch is merged with existing config.
+
+Apply changes via CLI: `echo '<json>' | railway environment edit --json`
+
+## Service Config
+
+### Source
+| Field | Type | Description |
+|-------|------|-------------|
+| `image` | string | Docker image (e.g., `nginx:latest`) |
+| `repo` | string | Git repository URL |
+| `branch` | string | Git branch to deploy |
+| `commitSha` | string | Specific commit SHA |
+| `rootDirectory` | string | Root directory (monorepos) |
+| `checkSuites` | boolean | Wait for GitHub check suites |
+| `autoUpdates.type` | disabled \| patch \| minor | Auto-update policy for Docker images |
+
+### Build
+| Field | Type | Description |
+|-------|------|-------------|
+| `builder` | NIXPACKS \| DOCKERFILE \| RAILPACK | Build system |
+| `buildCommand` | string | Command for Nixpacks builds |
+| `dockerfilePath` | string | Path to Dockerfile |
+| `watchPatterns` | string[] | Patterns to trigger deploys |
+| `nixpacksConfigPath` | string | Path to nixpacks config |
+
+### Deploy
+| Field | Type | Description |
+|-------|------|-------------|
+| `startCommand` | string | Container start command |
+| `multiRegionConfig` | object | Region → replica config. See [Multi-Region Config](#multi-region-config). |
+| `healthcheckPath` | string | Health check endpoint |
+| `healthcheckTimeout` | number | Seconds to wait for health |
+| `restartPolicyType` | ON_FAILURE \| ALWAYS \| NEVER | Restart behavior |
+| `restartPolicyMaxRetries` | number | Max restart attempts |
+| `cronSchedule` | string | Cron schedule for cron jobs |
+| `sleepApplication` | boolean | Sleep when inactive |
+
+### Variables
+| Field | Type | Description |
+|-------|------|-------------|
+| `value` | string | Variable value |
+| `isOptional` | boolean | Allow empty value |
+
+Set to `null` to delete a variable.
+
+For variable references, see [variables.md](variables.md).
+
+### Lifecycle
+| Field | Type | Description |
+|-------|------|-------------|
+| `isDeleted` | boolean | Mark for deletion (requires ADMIN) |
+| `isCreated` | boolean | Mark as newly created |
+
+## Multi-Region Config
+
+Controls replica count per region. Structure: region name → `{ numReplicas }` or `null` to remove.
+
+```json
+{
+  "multiRegionConfig": {
+    "us-west2": { "numReplicas": 3 },
+    "europe-west4-drams3a": { "numReplicas": 2 }
+  }
+}
+```
+
+### Available Regions
+
+| Name | Location | Aliases |
+|------|----------|---------|
+| `us-west2` | US West (California) | "us west", "california" |
+| `us-east4-eqdc4a` | US East (Virginia) | "us east", "virginia" |
+| `europe-west4-drams3a` | EU West (Amsterdam) | "europe", "eu", "amsterdam" |
+| `asia-southeast1-eqsg3a` | Southeast Asia (Singapore) | "asia", "singapore" |
+
+### Interpreting User Requests
+
+- "add 3 replicas to europe" → `{ "europe-west4-drams3a": { "numReplicas": 3 } }`
+- "add a replica to all regions" → set `numReplicas: 1` for all 4 regions
+- "remove from asia" → `{ "asia-southeast1-eqsg3a": null }`
+- "increase replicas to 5" (no region specified) → query current config first, update existing region(s)
+
+**Important:** When user doesn't specify a region, query the current `multiRegionConfig` and modify the existing region(s). Don't assume a default region.
+
+## Common Operations
+
+### Set Build Command
+```json
+{ "services": { "<serviceId>": { "build": { "buildCommand": "npm run build" } } } }
+```
+
+### Set Start Command
+```json
+{ "services": { "<serviceId>": { "deploy": { "startCommand": "node server.js" } } } }
+```
+
+### Set Replicas
+```json
+{ "services": { "<serviceId>": { "deploy": { "multiRegionConfig": { "us-west2": { "numReplicas": 3 } } } } } }
+```
+
+### Add Variables
+```json
+{ "services": { "<serviceId>": { "variables": { "API_KEY": { "value": "xxx" } } } } }
+```
+
+### Delete Variable
+```json
+{ "services": { "<serviceId>": { "variables": { "OLD_VAR": null } } } }
+```
+Via CLI: `echo '{"services":{"<serviceId>":{"variables":{"OLD_VAR":null}}}}' | railway environment edit --json`
+
+### Add Shared Variable
+```json
+{ "sharedVariables": { "DATABASE_URL": { "value": "postgres://..." } } }
+```
+
+### Change Docker Image
+```json
+{ "services": { "<serviceId>": { "source": { "image": "nginx:latest" } } } }
+```
+
+### Connect GitHub Repo
+```json
+{ "services": { "<serviceId>": { "source": { "repo": "owner/repo", "branch": "main" } } } }
+```
+
+### Change Git Branch
+```json
+{ "services": { "<serviceId>": { "source": { "branch": "develop" } } } }
+```
+
+### Set Health Check
+```json
+{ "services": { "<serviceId>": { "deploy": { "healthcheckPath": "/health", "healthcheckTimeout": 30 } } } }
+```
+
+### Change Builder
+```json
+{ "services": { "<serviceId>": { "build": { "builder": "DOCKERFILE", "dockerfilePath": "./Dockerfile" } } } }
+```
+
+### Delete Service
+```json
+{ "services": { "<serviceId>": { "isDeleted": true } } }
+```
+Via CLI: `echo '{"services":{"<serviceId>":{"isDeleted":true}}}' | railway environment edit --json`
+
+### Delete Volume
+```json
+{ "volumes": { "<volumeId>": { "isDeleted": true } } }
+```
+
+### New Service Instance
+```json
+{ "services": { "<serviceId>": { "isCreated": true, "source": { "image": "nginx" } } } }
+```
+
+**Note:** `isCreated: true` is required for new service instances.

package/skills/railway/projects/references/monorepo.md

@@ -0,0 +1,216 @@
+# Monorepo Reference
+
+Railway supports two types of monorepo deployments with different configuration approaches.
+
+## Key Decision: Root Directory vs Custom Commands
+
+| Approach | When to Use | What Happens |
+|----------|-------------|--------------|
+| **Root Directory** | Isolated apps (no shared code) | Only that directory's code is available |
+| **Custom Commands** | Shared monorepos (TypeScript, workspaces) | Full repo available, filter at build/start |
+
+**Critical:** Setting root directory means code outside that directory is NOT available during build. For monorepos with shared packages, use custom commands instead.
+
+## Isolated Monorepo
+
+Apps are completely independent - no shared code between directories.
+
+```
+├── frontend/        # React app (standalone)
+│   ├── package.json
+│   └── src/
+└── backend/         # Python API (standalone)
+    ├── requirements.txt
+    └── main.py
+```
+
+### Configuration
+
+Set **Root Directory** for each service:
+- Frontend service: `/frontend`
+- Backend service: `/backend`
+
+Each service only sees its own directory's code.
+
+### When to Use
+
+- Frontend and backend in different languages
+- No shared packages or dependencies
+- Each app has its own package.json/requirements.txt
+- Apps don't import from sibling directories
+
+## Shared Monorepo
+
+Apps share code from common packages or the root.
+
+```
+├── package.json           # Root workspace config
+├── packages/
+│   ├── frontend/
+│   │   ├── package.json
+│   │   └── src/
+│   ├── backend/
+│   │   ├── package.json
+│   │   └── src/
+│   └── shared/            # Shared utilities
+│       ├── package.json
+│       └── src/
+└── tsconfig.json          # Shared TS config
+```
+
+### Configuration
+
+Do NOT set root directory. Instead, use custom build and start commands:
+
+**pnpm:**
+```
+Build: pnpm --filter backend build
+Start: pnpm --filter backend start
+```
+
+**npm workspaces:**
+```
+Build: npm run build --workspace=packages/backend
+Start: npm run start --workspace=packages/backend
+```
+
+**yarn workspaces:**
+```
+Build: yarn workspace backend build
+Start: yarn workspace backend start
+```
+
+**bun:**
+```
+Build: bun run --filter backend build
+Start: bun run --filter backend start
+```
+
+**Turborepo:**
+```
+Build: turbo run build --filter=backend
+Start: turbo run start --filter=backend
+```
+
+### When to Use
+
+- TypeScript/JavaScript monorepo with workspaces
+- Packages import from sibling packages (`@myapp/shared`)
+- Shared tsconfig.json, eslint config at root
+- Using pnpm, yarn workspaces, npm workspaces, or bun
+- Using Turborepo, Nx, or similar build tools
+
+## Watch Paths
+
+Prevent changes in one package from triggering rebuilds of other services.
+
+Set watch paths for each service to only rebuild when relevant files change:
+
+| Service | Watch Paths |
+|---------|-------------|
+| frontend | `/packages/frontend/**`, `/packages/shared/**` |
+| backend | `/packages/backend/**`, `/packages/shared/**` |
+
+Include shared packages in watch paths if the service depends on them.
+
+### Pattern Format
+
+Uses gitignore-style patterns:
+```
+/packages/backend/**     # All files in backend
+/packages/shared/**      # All files in shared (if depends on it)
+!**/*.md                 # Ignore markdown changes
+```
+
+## Configuration Examples
+
+### Isolated: React + Python API
+
+Two separate apps, no shared code.
+
+**Frontend service:**
+- Root Directory: `/frontend`
+- No custom commands needed (Railpack auto-detects)
+
+**Backend service:**
+- Root Directory: `/backend`
+- No custom commands needed
+
+### Shared: TypeScript Monorepo with pnpm
+
+Frontend and backend share a `@myapp/shared` package.
+
+**Frontend service:**
+- Root Directory: (leave empty)
+- Build Command: `pnpm --filter frontend build`
+- Start Command: `pnpm --filter frontend start`
+- Watch Paths: `/packages/frontend/**`, `/packages/shared/**`
+
+**Backend service:**
+- Root Directory: (leave empty)
+- Build Command: `pnpm --filter backend build`
+- Start Command: `pnpm --filter backend start`
+- Watch Paths: `/packages/backend/**`, `/packages/shared/**`
+
+### Shared: Turborepo
+
+**Frontend service:**
+- Root Directory: (leave empty)
+- Build Command: `turbo run build --filter=frontend`
+- Start Command: `turbo run start --filter=frontend`
+- Watch Paths: `/apps/frontend/**`, `/packages/**`
+
+**Backend service:**
+- Root Directory: (leave empty)
+- Build Command: `turbo run build --filter=backend`
+- Start Command: `turbo run start --filter=backend`
+- Watch Paths: `/apps/backend/**`, `/packages/**`
+
+## Common Mistakes
+
+### Using Root Directory for Shared Monorepos
+
+**Wrong:**
+```
+Root Directory: /packages/backend
+```
+This breaks builds because `@myapp/shared` isn't available.
+
+**Right:**
+```
+Root Directory: (empty)
+Build Command: pnpm --filter backend build
+Start Command: pnpm --filter backend start
+```
+
+### Forgetting Watch Paths
+
+Without watch paths, changing `frontend/` triggers a rebuild of `backend/`.
+
+Always set watch paths for monorepos to avoid unnecessary builds.
+
+### Missing Shared Packages in Watch Paths
+
+If `backend` imports from `shared`, include both in watch paths:
+```
+/packages/backend/**
+/packages/shared/**
+```
+
+Otherwise changes to `shared` won't trigger backend rebuilds.
+
+## Detecting Monorepo Type
+
+Check for these indicators:
+
+**Isolated monorepo:**
+- Separate package.json in each directory
+- No workspace config in root package.json
+- No imports between directories
+
+**Shared monorepo:**
+- Root package.json with `workspaces` field
+- `pnpm-workspace.yaml` exists
+- Packages import from each other (`@myapp/shared`)
+- Shared tsconfig.json at root
+- turbo.json or nx.json at root