@arthai/agents 1.0.0

package/skills/onboard/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: onboard
+description: "Session onboarding — project briefing, work prioritization, and guided setup. Usage: /onboard"
+user-invocable: true
+arguments: ""
+---
+
+# Onboard Skill — Session Start Intelligence
+
+Helps users get oriented at the start of a session. Detects project state, gathers
+deep context, and suggests what to work on — prioritized by the nature of the project.
+Works for both greenfield and brownfield projects.
+
+**Key principle: Do the legwork, don't be pushy.** Gather context silently, present a
+clear picture, let the user drive.
+
+## Execution Steps
+
+### 1. Detect Project State
+
+Check these signals to determine greenfield vs brownfield:
+
+| Signal | Greenfield | Brownfield |
+|--------|-----------|------------|
+| `CLAUDE.md` exists | No | Yes |
+| Source code dirs (`src/`, `app/`, `backend/`, `frontend/`) | None | Present |
+| `package.json` or `requirements.txt` | None | Present |
+| Git history | 0-2 commits | Many commits |
+| `.claude/plans/` has files | No | Maybe |
+
+### 2A. Greenfield Flow
+
+If the project is greenfield (no meaningful code):
+
+1. Ask the user ONE question using AskUserQuestion:
+   - "What are you building? (1-2 sentences — what it does and who it's for)"
+
+2. Based on their answer, suggest a tech stack:
+   - Check if any config files hint at preferences (empty `package.json`, `requirements.txt`, etc.)
+   - Suggest a stack that matches their description
+   - Ask them to confirm or adjust
+
+3. Take action:
+   - Run `/scan` to scaffold CLAUDE.md with detected/chosen stack
+   - Create a project plan via `/planning` if the feature is non-trivial
+   - Or scaffold directly if it's simple enough
+
+4. Present next steps:
+   - "Project scaffolded. Run `/planning <feature>` to plan your first feature."
+   - "Or just tell me what to build and I'll get started."
+
+### 2B. Brownfield Flow
+
+If the project has existing code:
+
+#### Step 0: Toolkit Update Check (ALWAYS run first)
+
+Check if the claude-agents toolkit has been updated since this project last synced.
+This is the ONLY reliable way to surface toolkit changes to the user — hook stdout
+is unreliable (known Claude Code bugs #13650, #27467 cause silent drops).
+
+```bash
+# Read the per-project last-seen SHA
+TOOLKIT_DIR="$HOME/.claude-agents"
+LAST_SEEN_FILE=".claude/.toolkit-last-seen-sha"
+CURRENT_SHA=$(cd "$TOOLKIT_DIR" && git rev-parse HEAD 2>/dev/null)
+LAST_SEEN_SHA=$(cat "$LAST_SEEN_FILE" 2>/dev/null || echo "")
+
+# Compare — if different, toolkit has changed since last session
+if [ -n "$LAST_SEEN_SHA" ] && [ -n "$CURRENT_SHA" ] && [ "$LAST_SEEN_SHA" != "$CURRENT_SHA" ]; then
+    # Get commit count and details
+    cd "$TOOLKIT_DIR"
+    COMMIT_COUNT=$(git rev-list --count "$LAST_SEEN_SHA..$CURRENT_SHA" 2>/dev/null || echo "0")
+    CHANGELOG=$(git log --format="  • %s" "$LAST_SEEN_SHA..$CURRENT_SHA" 2>/dev/null | grep -iE "feat:|fix:|breaking:|new:" | head -5)
+    NEW_SKILLS=$(git diff --diff-filter=A --name-only "$LAST_SEEN_SHA..$CURRENT_SHA" -- "skills/*/SKILL.md" 2>/dev/null | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ', ' | sed 's/,$//')
+    UPDATED_AGENTS=$(git diff --diff-filter=M --name-only "$LAST_SEEN_SHA..$CURRENT_SHA" -- "agents/*.md" 2>/dev/null | sed 's|agents/||;s|\.md||' | tr '\n' ', ' | sed 's/,$//')
+fi
+
+# Also check if project hasn't been calibrated yet
+HAS_PROFILE=false
+[ -f ".claude/project-profile.md" ] && HAS_PROFILE=true
+```
+
+**If toolkit has changes, show them FIRST in the briefing:**
+
+```
+🔧 Toolkit updated ({COMMIT_COUNT} new commits since last session)
+{CHANGELOG}
+{if NEW_SKILLS: "  New skills: {NEW_SKILLS}"}
+{if UPDATED_AGENTS: "  Updated agents: {UPDATED_AGENTS}"}
+```
+
+**If project hasn't been calibrated, show the hint:**
+
+```
+💡 This project hasn't been calibrated yet. Run /calibrate to deep-learn your
+   codebase and configure MCP servers, agents, and workflows.
+```
+
+**After showing, update the stored SHA:**
+
+```bash
+echo "$CURRENT_SHA" > ".claude/.toolkit-last-seen-sha"
+```
+
+#### Step 1: Deep Context Gathering (no user interaction — run ALL of these)
+
+Use **parallel tool calls** where possible to gather all context fast.
+
+**Git state (local — fast)**:
+```bash
+git branch --show-current
+git status --short
+git log --oneline -20                    # recent commits for work history
+git log --oneline --since="3 days ago"   # what happened since last session
+git stash list
+git branch -a --sort=-committerdate | head -10  # recent branches
+```
+
+**GitHub state (if `gh` available)**:
+
+**Step 1 — fast list (run all in parallel):**
+```bash
+# My open PRs — NO comments field (bot comments are huge HTML and cause errors)
+gh pr list --author @me --json number,title,state,reviewDecision,updatedAt,headRefName,labels --limit 10
+
+# PRs requesting my review (--review-requested is NOT a valid flag; use --search)
+gh pr list --search "review-requested:@me" --json number,title,author,createdAt --limit 5
+
+# My assigned issues — get labels for prioritization
+gh issue list --assignee @me --json number,title,labels,createdAt,updatedAt --limit 10
+
+# Recent merged PRs (context on what shipped recently)
+gh pr list --state merged --limit 5 --json number,title,mergedAt,author
+
+# Open issues (unassigned — available to pick up)
+gh issue list --json number,title,labels,assignees --limit 10
+```
+
+**Step 2 — fetch comment details for PRs that need attention:**
+
+IMPORTANT: After Step 1, for each PR with `reviewDecision: CHANGES_REQUESTED`
+or updated in the last 3 days, fetch its comments individually. This avoids
+pulling massive bot comments in bulk while still getting the detail you need.
+
+```bash
+# Run ONE per PR that needs attention (replace <NUMBER> with actual PR number):
+gh pr view <NUMBER> --json comments,reviews --jq '{
+  comments: [.comments[] | {author: .author.login, age: .createdAt, body: .body[0:200]}] | .[-3:],
+  reviews: [.reviews[] | {author: .author.login, state: .state, body: .body[0:200]}] | .[-3:]
+}'
+```
+
+This gives you: who commented, when, and the first 200 chars of each comment.
+Include these details in the 🟡 Waiting on you section of the briefing.
+
+**Project state**:
+```bash
+ls .claude/plans/*.md                    # active plans
+cat CLAUDE.md | head -5                  # project identity
+```
+
+**Environment health** (read CLAUDE.md `## Environments` table):
+
+If the `## Environments` section exists in CLAUDE.md, validate each environment:
+
+```bash
+# For EACH environment in the Environments table:
+
+# Type: development (local)
+docker ps --format '{{.Names}} {{.Status}}'          # container health
+curl -sf {URL}{Health} > /dev/null && echo "✓" || echo "✗"  # local health endpoint
+# Check migration status (Alembic/Prisma/Drizzle — detect from project)
+ls .env.local > /dev/null 2>&1                        # env file exists
+
+# Type: staging
+curl -sf {URL}{Health} -o /dev/null -w "%{http_code}" # health endpoint
+# Check deploy platform accessibility (Railway MCP query, vercel whoami, etc.)
+
+# Type: production (READ-ONLY — never run mutations)
+curl -sf {URL}{Health} -o /dev/null -w "%{http_code}" # health endpoint only
+```
+
+**Fallback**: If no `## Environments` section exists in CLAUDE.md (project not yet calibrated), fall back to basic checks:
+```bash
+docker ps --format '{{.Names}} {{.Status}}'   # container health
+ls .env.local > /dev/null 2>&1                # env file exists
+# Check node_modules / venv freshness
+```
+
+Include environment status in the briefing output. Add to the existing tier format:
+
+In **🔴 Fix first** tier, add environment failures:
+```
+🔴 Fix first:
+   local — postgres container stopped
+     → Run: docker compose up -d postgres
+   staging — health check failed (503 at https://staging.myapp.com/health)
+     → Check: Railway dashboard or run /sre logs staging
+```
+
+When all environments are healthy, show as a compact status line before the tiers:
+```
+Environments: local ✓ | staging ✓ | production ✓
+```
+
+#### Step 2: Analyze & Prioritize
+
+Read the project's CLAUDE.md to understand the **nature of the project** and use that
+to weight priorities. Different projects care about different things:
+
+| Project Nature | Higher Priority | Lower Priority |
+|----------------|----------------|----------------|
+| Production app (users depend on it) | Prod bugs, failing CI, security issues | Feature requests, tech debt |
+| Early-stage startup | New features, user feedback | Test coverage, docs |
+| Internal tool | Requested features, reliability | Polish, edge cases |
+| Library/SDK | Breaking changes, test failures | New features |
+| CLI tool | UX bugs, install issues | Performance |
+
+**Smart prioritization rules**:
+- Issues with labels like `bug`, `critical`, `urgent`, `P0`, `security` → always 🔴
+- Issues with labels like `feature`, `enhancement` → 🔵 or ⚪ depending on age
+- Stale PRs (no activity > 7 days) → escalate to 🟡
+- PRs with `CHANGES_REQUESTED` → 🟡 (someone is waiting)
+- Branches with work but no PR → might be abandoned or mid-feature
+
+#### Step 3: Build the Briefing
+
+Organize findings into 4 tiers — **only show tiers that have items**:
+
+**🔴 Fix first** (blocking — things that prevent work):
+- Docker containers expected but not running
+- Migration mismatch (local behind head)
+- CI/CD failing on current branch
+- MCP servers disconnected
+- Critical bugs in production
+- Security issues
+
+**🟡 Waiting on you** (aging — things others are waiting for):
+- PR review comments unaddressed > 24h (show who commented, when)
+- PRs requesting your review (show author, title, age)
+- Issues assigned with approaching deadlines
+- Stale PRs with no activity > 7 days (show PR number, title, days stale)
+
+**🔵 Continue** (continuity — what you were doing last):
+- Uncommitted changes (you were mid-work) — list the files changed
+- Active plan file (you were mid-feature) — show which step
+- Current branch != main (you were on a feature) — show branch purpose
+- Recent commits that suggest in-progress work
+- Last session's work summary (group recent commits by area)
+
+**⚪ Available** (opportunity — things you could pick up):
+- Open issues nobody's assigned to (prioritized by label/nature)
+- PRs from teammates that need review
+- Next phase of an active plan
+- Recently merged PRs that might need follow-up (docs, tests, cleanup)
+
+#### Step 4: Present the Briefing
+
+Format as a structured message with actionable detail:
+
+```
+Here's where things stand:
+
+🔴 Fix first:
+   Docker redis is stopped — backend cache won't connect
+   → Run: docker compose up -d redis
+
+🟡 Waiting on you:
+   PR #245 "Fix auth token refresh" — 2 unresolved comments from @motred (3 days ago)
+      Last comment: "Need to handle the edge case where token is expired but refresh fails"
+   PR #251 by @teammate needs your review (opened 2 days ago)
+      "Add rate limiting to API endpoints"
+
+🔵 Continue from last session:
+   Branch: feature/oauth-support (3 uncommitted files: auth.ts, login.tsx, test_auth.py)
+   Plan: oauth-support.md — Step 3/5 (implementing token refresh)
+   Last commits:
+     • 2h ago: "add refresh token endpoint"
+     • 5h ago: "implement token storage in context"
+
+⚪ Available to pick up:
+   Issue #89 "Add password reset flow" (bug, assigned to nobody, 5 days old)
+   Issue #92 "Update onboarding copy" (enhancement, unassigned, 2 days old)
+   Plan: golden-dataset-pipeline.md — Phase 5 not started
+
+What would you like to tackle?
+
+🛠 Available workflows:
+  /planning <feature> → /implement → /qa → /review-pr → /pr     Feature development
+  /fix <bug|#issue>   → /review-pr → /pr                        Bug fix (formal pipeline)
+  /fix --hotfix       → /pr                                      Critical bug (expedited)
+  /calibrate                                                     Deep-learn project (first time)
+  /autopilot                                                     Autonomous work loop
+  /qa [full|staging|prod]                                        Run QA checks
+  /review-pr [#N]                                                Review a PR
+  /incident <description>                                         Something broken? Auto-triage + route
+  /ci-fix                                                        Fix failing CI
+  /sre [status|debug|deploy-check]                               SRE operations
+```
+
+**Key formatting rules**:
+- Show PR/issue numbers so user can reference them
+- Show who is waiting and how long (creates urgency naturally)
+- Show file names for uncommitted changes (reminds user what they were doing)
+- Show plan progress as "Step X/Y" or "Phase X"
+- Group recent commits by feature area (auth, billing, UI, etc.)
+- For stale PRs, show how many days since last activity
+- Include actionable next steps where obvious (run commands, review links)
+
+#### Step 5: Route Based on User's Choice
+
+- If user picks a red flag → route to ops agent or provide the fix command
+- If user picks a PR → route to code-reviewer or read the PR comments
+- If user picks continuing work → read the plan, route to appropriate agent
+- If user picks an issue → read the issue, route to /planning or direct fix
+- If user says "just fix the red flags" → fix them all, then re-present
+- If user says something specific → hand off to normal triage
+
+### 3. Edge Cases
+
+- **No git repo**: Skip all git/GitHub context. Just check for code files.
+- **No GitHub CLI**: Skip PR/issue context. Show git-only state.
+- **No Docker**: Skip container health. Show other context.
+- **User interrupts**: If user types something specific at any point, stop
+  onboarding and let triage handle their request normally.
+- **Nothing to report**: If everything is clean (main branch, no uncommitted,
+  no PRs, no issues), just say "Everything looks clean. What would you like to work on?"
+- **Too much to show**: If there are 10+ items across tiers, show top 3 per tier
+  and note "X more items — ask to see full list"
+
+## Rules
+
+- **Max 1 question** before presenting findings (brownfield: 0 questions)
+- **Never auto-start work** — always present and let user choose
+- **Degrade gracefully** — if a tool is missing, skip that context source
+- **Respect user's time** — if they have a specific task, get out of the way
+- **Toolkit updates go first** — always run Step 0 and show toolkit changes before
+  the project briefing. This is the only reliable way users see what changed.
+- **Calibration hint** — if `.claude/project-profile.md` doesn't exist, always show
+  the `/calibrate` hint. Don't skip it.
+- **Show the PR/issue content** — don't just count them, summarize what they're about
+- **Prioritize by project nature** — read CLAUDE.md to understand what matters most
+- **Use parallel tool calls** — gather all context sources simultaneously for speed

package/skills/opportunity-map/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: opportunity-map
+description: "Map AI opportunities by ROI and effort, recommend target orgs. Usage: /opportunity-map <client-name>"
+user-invocable: true
+arguments: "<client-name>"
+---
+
+# AI Opportunity Mapping
+
+Analyze a client's discovery data to identify, score, and prioritize AI opportunities. Produces a weighted priority matrix, phased roadmap, and department-level recommendations.
+
+## Prerequisites
+
+This skill requires completed discovery data. Check for files at:
+```
+clients/<client-name>/discovery/intake.md
+clients/<client-name>/discovery/current-state.md
+clients/<client-name>/discovery/maturity-assessment.md
+```
+
+If any of these files are missing, inform the user:
+```
+Discovery data not found for <client-name>. Run /client-discovery <client-name> first to complete the intake process.
+```
+Then stop execution.
+
+## Step 1 — Load Discovery Data
+
+1. Read all files in `clients/<client-name>/discovery/`
+2. Read `clients/<client-name>/profile.md`
+3. Extract and summarize:
+   - Top 3 pain points
+   - Business goals for AI
+   - Current tech stack and data readiness scores
+   - AI maturity composite score and readiness level
+   - Team capabilities and gaps
+   - Budget range and timeline expectations
+   - Industry and competitive landscape findings
+
+## Step 2 — Generate AI Initiatives
+
+Using the Jobs-to-Be-Done (JTBD) framework combined with the client's pain points, generate 8-15 AI initiative candidates. For each initiative, define:
+
+| Field | Description |
+|---|---|
+| **Name** | Short, descriptive name (e.g., "Intelligent Document Processing") |
+| **Description** | 2-3 sentence description of what the AI system does |
+| **Department** | Primary department affected (e.g., Operations, Sales, Finance, Customer Success, Engineering, HR, Marketing) |
+| **Type** | One of: `Automation` (replacing manual work), `Insight` (analytics/BI enhancement), `Generation` (content/code creation), `Prediction` (forecasting/classification) |
+| **Pain Point Addressed** | Which client pain point this directly addresses |
+| **JTBD** | The job the client is hiring this AI to do (format: "When [situation], I want to [motivation], so I can [outcome]") |
+| **Data Requirements** | What data is needed and whether the client likely has it |
+| **Tech Prerequisites** | What infrastructure/tools are needed |
+
+### Initiative Generation Guidelines
+
+- At least 2 initiatives per pain point mentioned by the client
+- Mix of types: aim for at least 2 Automation, 2 Insight, 1 Generation, 1 Prediction
+- Include at least 2 "quick wins" (low effort, fast time-to-value)
+- Include at least 1 "moonshot" (high impact, higher effort)
+- Consider the client's maturity level — lower maturity clients need simpler initiatives
+- Each initiative must be actionable with current or near-term AI capabilities (no speculative sci-fi)
+
+## Step 3 — Score Initiatives
+
+Score each initiative on 6 weighted factors using the following formula:
+
+### Scoring Factors
+
+| Factor | Weight | Scale | Description |
+|---|---|---|---|
+| Revenue Impact | 25% | 1-5 | Potential to increase revenue or market share |
+| Cost Savings | 20% | 1-5 | Potential to reduce operational costs |
+| Feasibility | 20% | 1-5 | Technical feasibility given current stack, data, and team |
+| Time to Value | 15% | 1-5 | Speed to first measurable results (5 = <1 month, 1 = >12 months) |
+| Strategic Alignment | 10% | 1-5 | Alignment with stated business goals and AI strategy |
+| Risk (inverse) | 10% | 1-5 | Low risk of failure or negative outcomes (5 = very low risk, 1 = very high risk) |
+
+### Weighted Score Formula
+
+```
+Weighted Score = (Revenue Impact × 0.25) + (Cost Savings × 0.20) + (Feasibility × 0.20)
+                + (Time to Value × 0.15) + (Strategic Alignment × 0.10) + (Risk Inverse × 0.10)
+
+Range: 1.00 to 5.00
+```
+
+### Score Interpretation
+
+| Score Range | Classification |
+|---|---|
+| 4.00 - 5.00 | Must-Do — prioritize immediately |
+| 3.00 - 3.99 | Should-Do — strong candidates for the roadmap |
+| 2.00 - 2.99 | Could-Do — consider if resources allow |
+| 1.00 - 1.99 | Defer — revisit in future cycles |
+
+Provide a brief justification (1-2 sentences) for each score.
+
+## Step 4 — Priority Matrix
+
+### 4a. ASCII 2x2 Impact/Effort Matrix
+
+Map each initiative onto a 2x2 matrix. Impact = (Revenue Impact + Cost Savings) / 2. Effort = inverse of (Feasibility + Time to Value) / 2.
+
+```
+                        HIGH IMPACT
+                            |
+         Strategic Bets     |     Quick Wins
+         (High effort,      |     (Low effort,
+          high impact)       |      high impact)
+                            |
+    ────────────────────────+────────────────────────
+                            |
+         Money Pits         |     Fill-Ins
+         (High effort,      |     (Low effort,
+          low impact)        |      low impact)
+                            |
+                        LOW IMPACT
+
+    HIGH EFFORT ◄───────────┼───────────► LOW EFFORT
+```
+
+Place each initiative by number/abbreviation in the appropriate quadrant.
+
+### 4b. Ranked Priority Table
+
+| Rank | Initiative | Type | Dept | Weighted Score | Quadrant | Wave |
+|---|---|---|---|---|---|---|
+| 1 | [Name] | [Type] | [Dept] | [X.XX] | Quick Win | 1 |
+| 2 | [Name] | [Type] | [Dept] | [X.XX] | Quick Win | 1 |
+| ... | ... | ... | ... | ... | ... | ... |
+
+Sort by weighted score descending.
+
+## Step 5 — Three-Wave Roadmap
+
+Assign each initiative to a wave based on its quadrant placement, dependencies, and the client's readiness level.
+
+### Wave 1: Quick Wins (Month 1-2)
+
+**Goal**: Build momentum and demonstrate ROI fast.
+
+Selection criteria:
+- Weighted score >= 3.50
+- Feasibility score >= 4
+- Time to Value score >= 4
+- Falls in "Quick Wins" quadrant
+- Minimal data preparation needed
+- Can use existing infrastructure
+
+For each Wave 1 initiative, provide:
+- Specific deliverables and milestones
+- Resource requirements (people, tools, data)
+- Expected measurable outcome within 60 days
+- Success metrics and KPIs
+
+### Wave 2: Foundation Building (Month 3-4)
+
+**Goal**: Establish infrastructure and capabilities for scaled AI.
+
+Selection criteria:
+- Weighted score >= 3.00
+- May require data pipeline work or new tooling
+- Falls in "Quick Wins" or "Strategic Bets" quadrant
+- Builds on Wave 1 learnings
+
+For each Wave 2 initiative, provide:
+- Dependencies on Wave 1 outcomes
+- Infrastructure investments needed
+- Team upskilling requirements
+- Expected outcomes by end of Month 4
+
+### Wave 3: Strategic Bets (Month 5-6)
+
+**Goal**: Deploy differentiated AI capabilities for competitive advantage.
+
+Selection criteria:
+- High revenue impact (>= 4) even if lower feasibility
+- Falls in "Strategic Bets" quadrant
+- Requires Wave 1-2 infrastructure
+- Longer time-to-value but high strategic importance
+
+For each Wave 3 initiative, provide:
+- Prerequisites from Waves 1-2
+- Investment required (budget estimate range)
+- Risk mitigation strategies
+- Long-term competitive advantage created
+
+### Roadmap Visualization
+
+```
+Month 1         Month 2         Month 3         Month 4         Month 5         Month 6
+├───────────────┼───────────────┼───────────────┼───────────────┼───────────────┤
+│◄──── Wave 1: Quick Wins ────►│                                               │
+│  [Initiative 1]               │                                               │
+│  [Initiative 2]               │                                               │
+│                               │◄──── Wave 2: Foundation ─────►│               │
+│                               │  [Initiative 3]                │               │
+│                               │  [Initiative 4]                │               │
+│                               │                                │◄── Wave 3 ──►│
+│                               │                                │  [Init 5]     │
+│                               │                                │  [Init 6]     │
+└───────────────────────────────┴────────────────────────────────┴───────────────┘
+```
+
+## Step 6 — Capability Mapping: Arth AI Agent Ecosystem → Client
+
+This is the differentiator. Map Arth AI's actual agent ecosystem to the client's departments and initiatives. Do NOT use generic descriptions — reference specific agents and skills by name.
+
+### Arth AI Agent Ecosystem Reference
+
+| Category | Agents | Skills | What They Do |
+|---|---|---|---|
+| **Software Engineering** | `architect`, `code-reviewer`, `frontend`, `python-backend` | `/implement`, `/ci-fix`, `/pr`, `/scan` | System design, AI-assisted code review, full-stack development, CI/CD automation |
+| **Quality Assurance** | `qa`, `qa-challenger`, `qa-baseline-updater`, `qa-domain`, `qa-e2e`, `qa-test-promoter` | `/qa`, `/qa-incident`, `/qa-learn` | Test strategy, automated test generation, quality gates, incident analysis |
+| **Product & Design** | `product-manager`, `design-studio-create`, `design-studio-critique`, `design-studio-think` | `/planning`, `/implement` | Product ideation, design iteration, UX critique, roadmap planning, feature buildout |
+| **Infrastructure & Ops** | `sre`, `ops` | `/sre`, `/deploy`, `/restart`, `/custom-domain` | Reliability engineering, deployment automation, incident response, infrastructure management |
+| **GTM & Sales** | `gtm-expert` | `/pitch-generator`, `/deliverable-builder`, `/market-research` | Market positioning, sales collateral, competitive analysis, case study creation |
+| **Strategy & Consulting** | `ai-consultant` | `/consulting`, `/client-discovery`, `/opportunity-map`, `/roi-calculator`, `/engagement-tracker` | Full consulting lifecycle — discovery to delivery |
+| **Onboarding & Setup** | `setup`, `explore-light` | `/setup`, `/onboard`, `/welcome`, `/explore` | Environment provisioning, team onboarding, codebase exploration |
+
+### Mapping Instructions
+
+For each client department, create a **Capability Mapping** that answers:
+
+1. **Which agents deploy to this department?** — Name the specific agents and what role they play
+2. **Which skills does the team use daily?** — Name the specific skills and what workflow they enable
+3. **What does this look like in practice?** — One concrete example scenario showing an agent in action (e.g., "Engineering lead asks the `architect` agent to design a recommendation engine. The agent produces a Mermaid architecture diagram, technology selection matrix, and implementation plan. The `code-reviewer` agent then reviews the first PR against the architecture.")
+4. **What's the quick win?** — One agent/skill the department can use within the first week
+
+### Department Brief Template
+
+```
+## [Department Name]
+
+### Current State
+- Current processes and workflows relevant to AI
+- Key pain points (from discovery)
+
+### Arth AI Agents & Skills Deployed
+| Agent/Skill | Role in This Department | Example Use |
+|---|---|---|
+| `agent-name` | [What it does for them] | [One-line concrete example] |
+| `/skill-name` | [What it does for them] | [One-line concrete example] |
+
+### What This Looks Like in Practice
+[2-3 sentence scenario showing how agents work together for this department. Be specific — name the agent, the input, and the output.]
+
+### New Capabilities Unlocked
+- [Capability 1 — tied to a specific agent/skill]
+- [Capability 2 — tied to a specific agent/skill]
+- [Capability 3 — tied to a specific agent/skill]
+
+### Quick Win (Week 1)
+- Deploy [specific agent/skill]
+- Input: [what the team provides]
+- Output: [what they get back]
+- Time: [hours, not weeks]
+```
+
+Generate a department brief for each unique department represented in the initiative list.
+
+### Cross-Department Synergies
+
+Identify where agents serve multiple departments:
+- Which agents create shared infrastructure?
+- Where does one department's output feed another's agent workflow?
+- What's the compounding effect of deploying the full ecosystem vs. individual agents?
+
+## Step 7 — Output Files
+
+Create the following files in `clients/<client-name>/`:
+
+### 7a. `assessment/opportunity-matrix.md`
+
+Contains:
+- Initiative catalog (Step 2) — full table of all 8-15 initiatives
+- Scoring breakdown (Step 3) — individual factor scores and weighted totals
+- Priority matrix ASCII diagram (Step 4a)
+- Ranked priority table (Step 4b)
+- Score justifications
+
+### 7b. `assessment/roadmap.md`
+
+Contains:
+- Three-wave roadmap with all initiative assignments (Step 5)
+- Timeline visualization
+- Dependencies and prerequisites
+- Resource and budget summary per wave
+- Success metrics and KPIs per wave
+- Risk register (top 3 risks per wave with mitigations)
+
+### 7c. `assessment/department-recommendations.md`
+
+Contains:
+- Department briefs (Step 6) for each affected department
+- Cross-department synergies and shared infrastructure
+- Organizational change management recommendations
+- Suggested governance model for AI initiatives
+
+## Notes
+
+- All scores must be justified with evidence from discovery data — no arbitrary numbers
+- If the client's maturity score is below 10, bias toward simpler, lower-risk initiatives
+- If budget is <$50K, focus exclusively on quick wins using existing tools and APIs
+- Flag any initiatives that require data the client may not have — these need data acquisition plans
+- Revisit opportunity map quarterly as the client's maturity evolves