@arthai/agents 1.0.0

package/skills/discord-ops/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: discord-ops
+description: Reference for Discord ChatOps commands — what can be invoked from Discord and how the system works.
+user-invocable: true
+---
+
+# /discord-ops — Discord ChatOps Reference
+
+This skill documents the Discord ChatOps integration that lets you control Claude Code from Discord.
+
+## Architecture
+
+```
+Discord #claude-ops → Bot listener (local Mac) → claude -p "<command>" → Result → Discord reply
+```
+
+The Discord MCP server (`~/discord-mcp/`) runs a chatops listener alongside the MCP tools.
+Commands typed in `#claude-ops` by authorized users are validated, then executed via Claude Code CLI.
+
+## Channels
+
+| Channel | Purpose |
+|---------|---------|
+| `#deployments` | Automated CI/CD notifications (webhook) |
+| `#claude-ops` | ChatOps commands — type here to control Claude Code |
+| `#general` | Manual posts (PR summaries, status updates) |
+
+## Available Commands (from Discord)
+
+### CI Failure Remediation
+| Command | What it does |
+|---------|-------------|
+| `fix ci` | Analyze latest CI failure, apply fixes, commit & push |
+| `ci status` | Check latest CI run status (pass/fail) |
+| `ci logs` | Get failure logs from latest failed CI run |
+| `ruff fix` | Auto-fix lint errors in backend + agent |
+| `fix types` | Check and report TypeScript errors |
+| `fix tests` | Run failing tests and report what broke |
+| `migration check` | Validate alembic migrations (heads, numbering) |
+
+### CI Fix Flow (from phone/Discord)
+```
+1. Get Discord alert in #deployments: "CI failed on branch X"
+2. Go to #claude-ops
+3. Type: ci logs          → see what failed
+4. Type: fix ci           → Claude reads logs, fixes, commits, pushes
+5. Type: ci status        → verify new CI run is passing
+```
+
+### SRE / Production
+| Command | What it does |
+|---------|-------------|
+| `/sre` | Full SRE agent for production debugging |
+| `check prod health` | Hit production health endpoints |
+| `check staging health` | Hit staging health endpoints |
+| `deploy status` | Check Railway deployment status |
+
+### QA & Testing
+| Command | What it does |
+|---------|-------------|
+| `/qa` | Run QA checks (commit mode) |
+| `run tests` | Run backend pytest + frontend jest |
+| `run lint` | Run linters without fixing |
+
+### Info (read-only)
+| Command | What it does |
+|---------|-------------|
+| `git status` | Show branch, changes, recent commits |
+| `pr status` | List open PRs |
+| `share latest prs` | Post PR summaries to Discord |
+| `show/find/search/explain ...` | Any read-only codebase query |
+
+### Ops
+| Command | What it does |
+|---------|-------------|
+| `/restart` | Restart local dev servers |
+| `/pr` | Create PR (runs QA first) — dangerous, use carefully |
+
+## Blocked Commands
+
+These patterns are always rejected for safety:
+- `rm -rf`, `sudo`, `git reset --hard`, `git push --force`
+- `DROP TABLE`, `DELETE FROM`
+- `railway up` (caused Feb 13 outage)
+- `pip uninstall`, `npm uninstall`
+- Anything containing `password`, `secret`, `token`, `api key`
+
+## Security
+
+- **Authorized users only**: Only Discord user IDs in `.env` can execute commands
+- **Channel-locked**: Only messages in `#claude-ops` are processed
+- **Allowlist-based**: Commands must match a known pattern — arbitrary commands rejected
+- **5-minute timeout**: Long-running commands are killed after 5 minutes
+- **Output truncated**: Results capped at 1900 chars to fit Discord limits
+
+## Setup
+
+The Discord MCP server at `~/discord-mcp/` must be running with chatops enabled:
+
+```bash
+# Required env vars in ~/discord-mcp/.env:
+DISCORD_TOKEN=<bot token>
+DISCORD_AUTHORIZED_USER_IDS=<comma-separated user IDs>
+DISCORD_OPS_CHANNEL=claude-ops
+CLAUDE_WORKING_DIR=/Users/pganapathy80/prepme
+CLAUDE_PATH=claude
+```
+
+To add a new authorized user:
+1. Get their Discord user ID (Developer Mode → right-click user → Copy User ID)
+2. Add to `DISCORD_AUTHORIZED_USER_IDS` in `~/discord-mcp/.env` (comma-separated)
+3. Restart the Discord MCP server
+
+## Restarting the Discord MCP Server
+
+```bash
+# Kill existing process
+pkill -f "discord-mcp/build/index.js"
+
+# Restart
+cd ~/discord-mcp && node build/index.js
+```
+
+Note: The MCP server runs in a terminal. Claude Code connects to it via stdio.
+Restarting it will require reconnecting Claude Code.

package/skills/engagement-tracker/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: engagement-tracker
+description: "Track consulting engagement progress and milestones. Usage: /engagement-tracker <client-name> [--action status|update|milestone]"
+user-invocable: true
+arguments: "<client-name> [--action status|update|milestone]"
+---
+
+# Engagement Tracker Skill
+
+Tracks consulting engagement progress, milestones, and status across all phases. Provides real-time dashboards, dated progress logs, and milestone management.
+
+## Trigger
+
+When the user invokes `/engagement-tracker <client-name>` with an optional `--action` flag. Defaults to `status` if no action is specified.
+
+## Prerequisites
+
+- Client profile at `clients/<client-name>/profile.json`
+- Engagement config at `clients/<client-name>/engagement.json` (created on first run if missing)
+- Tracking directory at `clients/<client-name>/tracking/`
+
+## Actions
+
+| Action | Purpose | Output |
+|--------|---------|--------|
+| `status` | Display ASCII dashboard with progress, RAG indicators, metrics | `tracking/status.md` |
+| `update` | Add a dated progress log entry | `tracking/updates.md` |
+| `milestone` | Mark a milestone complete and update tracking | `tracking/milestones.md` |
+
+## Steps
+
+### 1. Load Engagement State
+
+Read `clients/<client-name>/engagement.json`. If it does not exist, create it with this structure:
+
+```json
+{
+  "client_name": "[Company Name]",
+  "engagement_id": "[auto-generated: YYYY-MM-XXX]",
+  "start_date": "[YYYY-MM-DD]",
+  "target_end_date": "[YYYY-MM-DD]",
+  "status": "active",
+  "current_phase": "discovery",
+  "phases": {
+    "discovery": {
+      "name": "Discovery & Assessment",
+      "status": "in_progress",
+      "progress": 0,
+      "start_date": null,
+      "end_date": null,
+      "milestones": [
+        { "id": "D1", "name": "Client kickoff complete", "status": "pending", "date": null },
+        { "id": "D2", "name": "Stakeholder interviews complete", "status": "pending", "date": null },
+        { "id": "D3", "name": "Current state assessment delivered", "status": "pending", "date": null },
+        { "id": "D4", "name": "Market research delivered", "status": "pending", "date": null }
+      ]
+    },
+    "analysis": {
+      "name": "Analysis & Strategy",
+      "status": "not_started",
+      "progress": 0,
+      "start_date": null,
+      "end_date": null,
+      "milestones": [
+        { "id": "A1", "name": "Opportunity map complete", "status": "pending", "date": null },
+        { "id": "A2", "name": "ROI analysis delivered", "status": "pending", "date": null },
+        { "id": "A3", "name": "Initiative prioritization approved", "status": "pending", "date": null }
+      ]
+    },
+    "design": {
+      "name": "Solution Design",
+      "status": "not_started",
+      "progress": 0,
+      "start_date": null,
+      "end_date": null,
+      "milestones": [
+        { "id": "S1", "name": "Architecture design complete", "status": "pending", "date": null },
+        { "id": "S2", "name": "Technology selection finalized", "status": "pending", "date": null },
+        { "id": "S3", "name": "Implementation plan approved", "status": "pending", "date": null },
+        { "id": "S4", "name": "Cost model delivered", "status": "pending", "date": null }
+      ]
+    },
+    "delivery": {
+      "name": "Deliverable Creation",
+      "status": "not_started",
+      "progress": 0,
+      "start_date": null,
+      "end_date": null,
+      "milestones": [
+        { "id": "V1", "name": "Final report delivered", "status": "pending", "date": null },
+        { "id": "V2", "name": "Board deck delivered", "status": "pending", "date": null },
+        { "id": "V3", "name": "Implementation guide delivered", "status": "pending", "date": null },
+        { "id": "V4", "name": "Client sign-off received", "status": "pending", "date": null }
+      ]
+    }
+  },
+  "overall_rag": "GREEN",
+  "blockers": [],
+  "next_actions": [],
+  "updates": []
+}
+```
+
+Prompt the user for `start_date` and `target_end_date` if creating fresh.
+
+### 2. Execute Action
+
+---
+
+#### Action: `status` (Default)
+
+Generate an ASCII dashboard showing comprehensive engagement status.
+
+**Full ASCII Dashboard Template:**
+
+```
+╔══════════════════════════════════════════════════════════════════════╗
+║                    ENGAGEMENT STATUS DASHBOARD                      ║
+║  Client: [Company Name]                                             ║
+║  Engagement: [ID]                 Status: [ACTIVE/ON HOLD/COMPLETE] ║
+║  Period: [Start Date] to [Target End Date]                          ║
+║  Report Date: [Today's Date]                                        ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  OVERALL STATUS: [RAG]  [GREEN/YELLOW/RED indicator]                 ║
+║                                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  PHASE PROGRESS                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  1. Discovery & Assessment                                           ║
+║     [████████████████████░░░░░░░░░░] 65%  Status: IN PROGRESS        ║
+║     Milestones: 2/4 complete                                         ║
+║     [x] D1: Client kickoff complete (2026-03-15)                     ║
+║     [x] D2: Stakeholder interviews complete (2026-03-20)             ║
+║     [ ] D3: Current state assessment delivered                       ║
+║     [ ] D4: Market research delivered                                ║
+║                                                                      ║
+║  2. Analysis & Strategy                                              ║
+║     [████████░░░░░░░░░░░░░░░░░░░░░] 25%  Status: IN PROGRESS        ║
+║     Milestones: 1/3 complete                                         ║
+║     [x] A1: Opportunity map complete (2026-03-22)                    ║
+║     [ ] A2: ROI analysis delivered                                   ║
+║     [ ] A3: Initiative prioritization approved                       ║
+║                                                                      ║
+║  3. Solution Design                                                  ║
+║     [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  0%  Status: NOT STARTED        ║
+║     Milestones: 0/4 complete                                         ║
+║                                                                      ║
+║  4. Deliverable Creation                                             ║
+║     [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  0%  Status: NOT STARTED        ║
+║     Milestones: 0/4 complete                                         ║
+║                                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  OVERALL PROGRESS                                                    ║
+║  [██████████░░░░░░░░░░░░░░░░░░░░░] 30%                               ║
+║  Milestones: 3/15 complete                                           ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  KEY METRICS                                                         ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  Days Elapsed:     [X] / [Total]    Time Used:  [██████░░░░] XX%     ║
+║  Milestones Done:  [X] / [Total]    On Track:   [YES/NO]            ║
+║  Deliverables:     [X] / [Total]    Next Due:   [Date]              ║
+║  Open Blockers:    [X]              Risk Level: [LOW/MED/HIGH]       ║
+║                                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  RAG SUMMARY                                                         ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  Schedule:   [GREEN/YELLOW/RED]  [Explanation]                       ║
+║  Scope:      [GREEN/YELLOW/RED]  [Explanation]                       ║
+║  Resources:  [GREEN/YELLOW/RED]  [Explanation]                       ║
+║  Quality:    [GREEN/YELLOW/RED]  [Explanation]                       ║
+║  Stakeholder:[GREEN/YELLOW/RED]  [Explanation]                       ║
+║                                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  BLOCKERS & RISKS                                                    ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  [RED]  #1: [Blocker description] — Owner: [Name], Since: [Date]     ║
+║  [YLW]  #2: [Risk description] — Probability: [H/M/L], Impact: [H/M]║
+║                                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  NEXT ACTIONS                                                        ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  1. [Action item] — Owner: [Name], Due: [Date]                       ║
+║  2. [Action item] — Owner: [Name], Due: [Date]                       ║
+║  3. [Action item] — Owner: [Name], Due: [Date]                       ║
+║                                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  RECENT UPDATES                                                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  [Date]: [Brief summary of most recent update]                       ║
+║  [Date]: [Brief summary of previous update]                          ║
+║                                                                      ║
+╚══════════════════════════════════════════════════════════════════════╝
+```
+
+**Progress bar rendering logic:**
+
+```
+Progress bar width: 30 characters
+Filled character: █ (U+2588)
+Empty character: ░ (U+2591)
+
+Calculate filled = round(progress / 100 * 30)
+Calculate empty = 30 - filled
+
+Example: 65% = ████████████████████░░░░░░░░░░ (19.5 rounded to 20 filled, 10 empty)
+```
+
+**RAG indicator logic:**
+
+```
+GREEN:  On track, no issues
+YELLOW: Minor issues, mitigation in progress, at risk of slipping
+RED:    Blocked, significantly behind schedule, requires escalation
+
+Overall RAG = worst RAG across all dimensions (schedule, scope, resources, quality, stakeholder)
+```
+
+**Compute metrics from engagement.json:**
+- Days elapsed = today - start_date
+- Total days = target_end_date - start_date
+- Time used % = days elapsed / total days * 100
+- Milestones done = count of milestones with status "complete" across all phases
+- Total milestones = count of all milestones across all phases
+- Overall progress = weighted average of phase progress (equal weights)
+- On Track = YES if progress % >= time used %, otherwise NO
+
+Write the dashboard to `tracking/status.md` and also display it in the terminal output.
+
+---
+
+#### Action: `update`
+
+Add a dated progress log entry. Prompt the user for update details or accept them as part of the invocation.
+
+**Update entry format in `tracking/updates.md`:**
+
+```markdown
+---
+
+## Update: [YYYY-MM-DD]
+**Author:** [Name]
+**Phase:** [Current Phase]
+**Overall Status:** [GREEN/YELLOW/RED]
+
+### Activities Completed
+- [Activity 1]
+- [Activity 2]
+- [Activity 3]
+
+### Decisions Made
+- [Decision 1]: [Context and rationale]
+- [Decision 2]: [Context and rationale]
+
+### Risks & Issues
+| # | Type | Description | Impact | Mitigation | Status |
+|---|------|-------------|--------|------------|--------|
+| 1 | | | | | |
+
+### Next Steps
+- [ ] [Action 1] — Owner: [Name], Due: [Date]
+- [ ] [Action 2] — Owner: [Name], Due: [Date]
+
+### Notes
+[Any additional context, observations, or stakeholder feedback]
+```
+
+After adding the update entry:
+1. Append the entry to `tracking/updates.md` (do not overwrite previous entries)
+2. Update `engagement.json` with:
+   - Add entry to `updates` array with date and summary
+   - Update `next_actions` with the new next steps
+   - Update `blockers` if any new blockers were identified
+   - Update phase `progress` if activities completed warrant it
+3. Regenerate the status dashboard (`tracking/status.md`) with latest data
+
+---
+
+#### Action: `milestone`
+
+Mark a milestone as complete and update all tracking artifacts.
+
+**Steps:**
+
+1. Display the current milestone list with IDs:
+   ```
+   Discovery & Assessment:
+     [ ] D1: Client kickoff complete
+     [x] D2: Stakeholder interviews complete (2026-03-20)
+     [ ] D3: Current state assessment delivered
+     [ ] D4: Market research delivered
+
+   Analysis & Strategy:
+     [ ] A1: Opportunity map complete
+     ...
+   ```
+
+2. Prompt the user for the milestone ID to mark complete (e.g., "D3"), or accept it as a parameter.
+
+3. Update `engagement.json`:
+   - Set the milestone's `status` to `"complete"`
+   - Set the milestone's `date` to today's date
+   - Recalculate phase `progress` = (completed milestones / total milestones) * 100
+   - If all milestones in a phase are complete, set phase `status` to `"complete"` and `end_date` to today
+   - If this is the first milestone completed in a phase, set phase `start_date` if not already set
+   - Auto-advance `current_phase` if current phase is fully complete
+
+4. Add a milestone completion entry to `tracking/milestones.md`:
+
+   ```markdown
+   ---
+
+   ## Milestone Completed: [ID] — [Name]
+   **Date:** [YYYY-MM-DD]
+   **Phase:** [Phase Name]
+   **Phase Progress:** [X]% ([completed]/[total] milestones)
+
+   ### Milestone Details
+   - **Description:** [What this milestone represents]
+   - **Deliverables:** [Files or outputs produced]
+   - **Key Outcomes:** [What was achieved]
+
+   ### Phase Status After Completion
+   - Progress: [██████████████░░░░░░░░░░░░░░░] [X]%
+   - Remaining Milestones:
+     - [ ] [Next milestone in phase]
+     - [ ] [Next milestone in phase]
+   ```
+
+5. Display a completion confirmation:
+
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  MILESTONE COMPLETE                                         ║
+   ║                                                              ║
+   ║  [ID]: [Milestone Name]                                      ║
+   ║  Date: [YYYY-MM-DD]                                          ║
+   ║  Phase: [Phase Name] — [X]% complete                         ║
+   ║                                                              ║
+   ║  Overall Engagement: [X]% complete ([X]/[Total] milestones)  ║
+   ╚══════════════════════════════════════════════════════════════╝
+   ```
+
+6. Regenerate the status dashboard with updated data.
+
+### 3. Persist State
+
+After every action:
+
+1. Write updated `engagement.json` with all changes
+2. Write/update the appropriate tracking file:
+   - `status`: `tracking/status.md`
+   - `update`: `tracking/updates.md` (append)
+   - `milestone`: `tracking/milestones.md` (append)
+3. Display confirmation of what was updated
+
+### 4. Edge Cases
+
+- **First run:** Create `engagement.json`, `tracking/` directory, and all tracking files
+- **Stale dashboard:** If `tracking/status.md` is older than the latest update, regenerate automatically
+- **Phase transitions:** When all milestones in a phase complete, auto-advance to next phase and notify user
+- **Engagement completion:** When all phases complete, set `status` to `"complete"` and generate final summary
+- **Backdated milestones:** Allow `--date YYYY-MM-DD` to mark milestones completed on a past date
+
+## Quality Checklist
+
+Before finalizing output:
+- [ ] Progress bars accurately reflect milestone completion ratios
+- [ ] RAG indicators are justified (not just default green)
+- [ ] Dates are in YYYY-MM-DD format consistently
+- [ ] Milestone IDs are unique and referenced correctly
+- [ ] engagement.json is valid JSON after updates
+- [ ] Updates are appended, never overwriting previous entries
+- [ ] Dashboard displays correctly in terminal (no broken box-drawing characters)

package/skills/explore.md

@@ -0,0 +1,43 @@
+---
+name: explore
+description: Fast codebase exploration using Haiku. Use for finding files, searching code, understanding structure.
+user-invocable: true
+---
+
+# Explore Skill
+
+Use the explore-light agent to answer the user's exploration query efficiently with Haiku.
+
+## Instructions
+
+1. Parse the user's query from the skill arguments
+2. Spawn the explore-light agent using the Task tool with:
+   - `subagent_type: "explore-light"`
+   - `model: "haiku"`
+   - `prompt: <user's exploration query>`
+3. Return the agent's findings to the user
+
+## Example Usage
+
+```
+User: /explore find all API route handlers
+Action: Spawn explore-light agent with prompt "find all API route handlers"
+
+User: /explore how does authentication work
+Action: Spawn explore-light agent with prompt "how does authentication work in this codebase"
+
+User: /explore where is the database schema defined
+Action: Spawn explore-light agent with prompt "where is the database schema defined"
+```
+
+## When to Use
+
+- Finding files by pattern or name
+- Searching for specific functions, classes, or patterns
+- Understanding directory structure
+- Quick "where is X" questions
+- Summarizing code organization
+
+## Cost Benefit
+
+This skill uses Haiku (~60x cheaper than Opus) for exploration tasks that don't require deep reasoning.