@arthai/agents 1.0.0

package/skills/ci-fix/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: ci-fix
+description: "Auto-remediate CI, staging, and production failures. 3-attempt retry with investigation. Discord alert on exhaustion. Usage: /ci-fix [ci|staging|prod] [branch]"
+user-invocable: true
+arguments: "<mode> <branch>"
+---
+
+# /ci-fix — Unified Auto-Remediation
+
+Automatically diagnose and fix CI failures, staging deploy failures, and production deploy failures. Retries up to 3 times. Alerts on Discord `#deployments` if all attempts fail.
+
+## Project Context Discovery (Deep)
+
+Before attempting any fix, understand the FULL CI/CD landscape.
+
+### Step 1: Read existing context
+
+Read in this order (skip gracefully if missing):
+1. `CLAUDE.md` — Test Commands table, Infrastructure table
+2. `.claude/project-profile.md` — CI platform, test frameworks (from /calibrate)
+3. `.claude/knowledge/skills/ci-fix.md` — Past CI failures and patterns
+4. `.claude/qa-knowledge/incidents/` — Past incidents from CI failures
+5. `.claude/qa-knowledge/bug-patterns.md` — Known failure patterns
+
+### Step 2: Detect CI platform
+
+Don't assume GitHub Actions. Detect the actual CI system:
+
+| Signal | CI Platform | How to get logs | How to check status | How to retry |
+|--------|------------|----------------|--------------------|----|
+| `.github/workflows/*.yml` | GitHub Actions | `gh run view <id> --log-failed` | `gh run list --branch <b>` | `gh run rerun <id>` |
+| `.gitlab-ci.yml` | GitLab CI | `glab ci view --branch <b>` | `glab ci status` | `glab ci retry` |
+| `Jenkinsfile` | Jenkins | Jenkins API: `/job/<name>/lastBuild/consoleText` | Jenkins API: `/job/<name>/lastBuild/api/json` | Jenkins API: `/job/<name>/build` |
+| `.circleci/config.yml` | CircleCI | `circleci` CLI or API | `circleci` CLI | API trigger |
+| `bitbucket-pipelines.yml` | Bitbucket Pipelines | Bitbucket API | Bitbucket API | API trigger |
+| `.buildkite/pipeline.yml` | Buildkite | `buildkite-agent` or API | API | `bk build retry` |
+| `azure-pipelines.yml` | Azure Pipelines | `az pipelines runs show` | `az pipelines runs list` | `az pipelines run` |
+| `.travis.yml` | Travis CI | Travis API | Travis API | API trigger |
+| `Taskfile.yml` + CI wrapper | Task-based | Depends on wrapper CI | Depends | Depends |
+
+If MULTIPLE CI systems detected (e.g., GitHub Actions for CI + ArgoCD for deploy), document both.
+
+### Step 3: Detect test infrastructure
+
+Map the project's test stack so fixes target the right layer:
+
+| Signal | Test Layer | Fix Strategy |
+|--------|-----------|-------------|
+| `pytest.ini` / `pyproject.toml [tool.pytest]` | Python unit/integration | Fix Python code, run `pytest` locally |
+| `jest.config.*` / `vitest.config.*` | JS/TS unit tests | Fix JS/TS code, run `npm test` locally |
+| `playwright.config.*` / `cypress.config.*` | E2E tests | May need running services, check docker-compose |
+| `ruff.toml` / `.flake8` / `.eslintrc.*` | Linting | Auto-fix with `ruff check --fix` / `eslint --fix` |
+| `mypy.ini` / `tsconfig.json` | Type checking | Fix type annotations |
+| `Dockerfile` / `docker-compose.test.yml` | Containerized tests | Build container first, then run |
+| `tox.ini` | Multi-env Python testing | Run specific tox env |
+| `Makefile` with test targets | Make-based | Run `make test` |
+
+### Step 4: Detect environment requirements
+
+CI often fails because of environment differences. Check:
+
+```bash
+# What Python/Node/Go version does CI use?
+grep -r "python-version\|node-version\|go-version" .github/workflows/ .gitlab-ci.yml 2>/dev/null
+
+# What services does CI spin up? (postgres, redis, etc.)
+grep -r "services:" .github/workflows/ 2>/dev/null
+grep -r "image:" .gitlab-ci.yml 2>/dev/null
+
+# What env vars does CI set?
+grep -r "env:" .github/workflows/ 2>/dev/null | grep -v "#"
+
+# What secrets are used?
+grep -r "secrets\." .github/workflows/ 2>/dev/null
+```
+
+### Step 5: Check for known flaky patterns
+
+Before investigating a failure, check if it's a known issue:
+
+```bash
+# Check past CI fix incidents
+grep -l "ci-fix\|CI\|flaky" .claude/qa-knowledge/incidents/ 2>/dev/null
+
+# Check knowledge base for CI patterns
+cat .claude/knowledge/skills/ci-fix.md 2>/dev/null | grep -A3 "## Patterns"
+```
+
+If a known flaky test matches the failure, report it instead of debugging.
+
+### Step 6: Recommend CI improvements
+
+After every fix (or on first run), check for CI best practices:
+
+```
+CI recommendations for {project}:
+  ⚠ No dependency caching — CI runs will be slow
+    Add: actions/cache for node_modules / .venv / cargo
+  ⚠ No test parallelism — tests run sequentially
+    Add: pytest-xdist / jest --workers / go test -parallel
+  ⚠ No test timeout — flaky tests can hang forever
+    Add: timeout-minutes in workflow / pytest --timeout=30
+  ⚠ No retry for flaky tests — one flake fails the whole run
+    Add: pytest-rerunfailures / jest --retry
+  ⚠ Services not health-checked — tests may start before DB is ready
+    Add: health check options to service containers
+  ⚠ No artifact upload on failure — can't debug after the run
+    Add: actions/upload-artifact for test reports on failure
+```
+
+## Mode Detection
+
+Parse from arguments:
+- No argument / `ci` → **CI mode** — fix GitHub Actions lint/test/build failures
+- `staging` → **Staging mode** — investigate + fix staging deployment failures
+- `prod` / `production` → **Prod mode** — investigate + fix production deployment failures
+- Optional second arg: branch name (default: current branch)
+
+## Architecture
+
+```
+Failure detected → /ci-fix invoked
+  → Determine mode (CI / staging / prod)
+  → Attempt 1: diagnose → fix → verify → push/redeploy
+    → Green? DONE
+    → Still failing? Attempt 2 (different strategy)
+  → Attempt 2: re-diagnose → fix → verify → push/redeploy
+    → Green? DONE
+    → Still failing? Attempt 3 (escalate approach)
+  → Attempt 3: deep investigation → fix → verify → push/redeploy
+    → Green? DONE
+    → Still failing? → Discord alert + QA incident file
+```
+
+---
+
+## CI Mode (default)
+
+Fix GitHub Actions lint, type, test, and build failures.
+
+### Per-Attempt Steps
+
+#### Step 1: Identify the failure
+
+```bash
+BRANCH=$(git branch --show-current)
+gh run list --branch "$BRANCH" --limit 5 --json databaseId,conclusion,status,name
+```
+
+Get failed run logs:
+```bash
+gh run view <FAILED_RUN_ID> --log-failed 2>&1 | tail -200
+```
+
+#### Step 2: Classify and fix
+
+| Category | Indicators | Fix Strategy |
+|----------|-----------|--------------|
+| **Lint** | ruff/eslint errors | Auto-fix tools scoped to specific directories |
+| **Type errors** | tsc/mypy failures | Read error file:line, fix type annotation |
+| **Test failures** | pytest/jest failures | Read failing test + source, fix root cause |
+| **Build failures** | build errors | Read error, fix import/export/config |
+| **Migration** | Alembic/Django errors | Fix migration file |
+| **Dependency** | pip/npm install failures | Fix requirements/package.json |
+
+**Attempt escalation:**
+- Attempt 1: Apply the obvious fix (auto-fix tools, direct code fix)
+- Attempt 2: Read more context (surrounding code, related tests, recent commits)
+- Attempt 3: Deep investigation — read git log, compare against last green commit
+
+#### Step 3: Verify locally (MANDATORY before pushing)
+
+Run ONLY the checks that failed — use commands from CLAUDE.md Test Commands table.
+
+#### Step 4: Commit, push, wait for CI
+
+```bash
+git add <only_changed_files>
+git commit -m "$(cat <<'EOF'
+fix: <category> — <what was fixed>
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+git push
+```
+
+Wait for CI result:
+```bash
+sleep 90 && gh run list --branch "$BRANCH" --limit 1 --json conclusion,status
+```
+
+---
+
+## Staging Mode
+
+Investigate and fix staging deployment failures.
+
+1. **Diagnose**: Check deployment platform health endpoints (from CLAUDE.md), get deploy logs
+2. **Classify**: Migration failed, missing env var, health timeout, build error, runtime crash
+3. **Fix**: Code fix → verify locally → push. Env var fix → use platform tools.
+4. **Verify**: Wait for deploy, check all health endpoints
+
+---
+
+## Prod Mode
+
+Same as staging but with **extra caution**:
+- NEVER modify production database directly
+- NEVER run destructive commands against production
+- Fix code locally → push to main → platform auto-deploys
+- On attempt 3, consider rollback: `git revert HEAD --no-edit && git push`
+
+---
+
+## After 3 Failed Attempts (ALL MODES)
+
+### 1. Discord alert (if discord-ops is configured)
+
+```
+mcp__discord-mcp__send-message(
+  channel: "deployments",
+  message: "Auto-Fix Failed — 3 attempts exhausted\n\nMode: {mode}\nBranch: {branch}\nError: {last_error_summary}\n\nAction needed: Manual review required."
+)
+```
+
+### 2. Write QA incident
+
+Create `.claude/qa-knowledge/incidents/{date}-autofix-exhausted-{slug}.md` with root cause, how QA missed it, and regression test recommendation.
+
+### 3. Report to user
+
+```
+Auto-fix exhausted after 3 attempts ({mode} mode) on `{branch}`.
+QA incident logged.
+Manual review required.
+```
+
+---
+
+## Rules (ALL MODES)
+
+- **NEVER** run lint auto-fix on the entire repo — scope to specific directories
+- **NEVER** modify dependency files unless that's the actual failure
+- **NEVER** add `# type: ignore` or `# noqa` to suppress errors — fix them properly
+- **NEVER** delete or skip tests — fix the underlying issue
+- **NEVER** use `railway up` or equivalent — always push to git for auto-deploy
+- **ALWAYS** verify locally before pushing
+- **ALWAYS** scope fixes narrowly — only touch files that caused the failure
+- **ALWAYS** try a DIFFERENT strategy on each retry
+- Maximum 3 attempts. After that, alert humans.
+- If fix requires architectural changes → report and stop, don't attempt large refactors
+
+## Knowledge Base Integration
+
+### On every /ci-fix invocation:
+1. **Read** `.claude/knowledge/skills/ci-fix.md` for past failure patterns
+2. **Read** `.claude/qa-knowledge/incidents/` for similar past CI incidents
+3. **Match** current failure against known patterns before investigating
+
+### After every fix (success or exhaustion):
+1. **Append** to `.claude/knowledge/skills/ci-fix.md`:
+   ```
+   ### {date} — {failure type}
+   **CI Platform**: {platform}
+   **Category**: {lint | type | test | build | migration | dependency | flaky}
+   **Root cause**: {what was wrong}
+   **Fix**: {what was done}
+   **Attempts**: {N}
+   **Was it a known pattern?**: {yes — matched incident X | no — new pattern}
+   **Prevention**: {how to avoid next time}
+   ```
+
+2. If failure was a NEW pattern (not in knowledge base):
+   - Add to `.claude/qa-knowledge/bug-patterns.md` under CI section
+   - Consider: should this become a pre-push check?
+
+3. If fix took 3 attempts (exhaustion):
+   - Create incident: `.claude/qa-knowledge/incidents/{date}-ci-exhaust-{slug}.md`
+   - Flag as systemic if same category failed 3+ times in knowledge base
+
+### /calibrate Integration
+
+When `/calibrate` runs, it reads CI configuration to understand the project's test pipeline.
+The /ci-fix skill contributes:
+1. **CI platform detection** → /calibrate writes to project profile
+2. **Test infrastructure map** → /calibrate includes in profile "Testing Conventions" section
+3. **Environment requirements** → /calibrate notes version mismatches between local and CI
+4. **Flaky test inventory** → /calibrate includes in recommendations
+5. **CI improvement recommendations** → /calibrate includes in "Recommended Tools" section
+
+If `/calibrate` hasn't run, /ci-fix does its own discovery and recommends running `/calibrate`.
+If `/calibrate` has run, /ci-fix reads the profile instead of re-discovering.

package/skills/client-discovery/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: client-discovery
+description: "Client discovery and AI readiness assessment. Usage: /client-discovery <client-name> [-- <brief>]"
+user-invocable: true
+arguments: "<client-name> [-- brief]"
+---
+
+# Client Discovery & AI Readiness Assessment
+
+Run a structured discovery process for a prospective consulting client. Gathers business context, assesses current technology, evaluates AI maturity, researches the competitive landscape, and produces a complete client profile with readiness scoring.
+
+## Step 1 — Intake Interview
+
+Conduct a structured intake interview using AskUserQuestion. Questions are organized into three groups. If the user provided a `<brief>` after `--`, scan it first and skip any questions already answered. For skipped questions, confirm the extracted answer with the user.
+
+### Group A — Business Context (5 questions)
+
+Ask these questions one group at a time. Present all questions in the group together so the user can answer in a single response.
+
+```
+Business Context — please answer the following:
+
+1. What is the company's full legal name and any brand names?
+2. What is the company size? (headcount and/or revenue range)
+3. What industry or vertical does the company operate in? (e.g., fintech, healthcare, logistics, retail)
+4. What is the approximate annual revenue range? (e.g., <$1M, $1-10M, $10-50M, $50-200M, $200M+)
+5. What is the primary business model? (e.g., SaaS, marketplace, services, e-commerce, manufacturing)
+```
+
+### Group B — Current Technology (4 questions)
+
+```
+Current Technology — please answer the following:
+
+6. What is your current tech stack? (languages, frameworks, cloud providers, key SaaS tools)
+7. Describe your data infrastructure. (databases, data warehouses, ETL pipelines, BI tools)
+8. Are you currently using any AI/ML? If so, what? (e.g., chatbots, recommendation engines, predictive models, none)
+9. What is the size and structure of your IT/engineering team? (e.g., 5 engineers, 2 data analysts, outsourced dev shop)
+```
+
+### Group C — Pain Points & Goals (4 questions)
+
+```
+Pain Points & Goals — please answer the following:
+
+10. What are your top 3 business pain points right now?
+11. What are your goals for AI adoption? (e.g., reduce costs, improve CX, new revenue streams, competitive advantage)
+12. What is your timeline expectation for seeing results? (e.g., 1-3 months, 3-6 months, 6-12 months)
+13. What is your approximate budget range for an AI initiative? (e.g., <$50K, $50-150K, $150-500K, $500K+)
+```
+
+Record all answers verbatim. If a user declines to answer a question, record "Not disclosed" and move on.
+
+## Step 2 — Current State Analysis
+
+Using the intake answers, produce the following analyses:
+
+### 2a. Business Model Summary
+
+Write a 2-3 paragraph narrative summary covering:
+- What the company does and how it makes money
+- Key customer segments and value propositions
+- Market position and competitive dynamics
+
+### 2b. Tech Stack Diagram
+
+Generate a Mermaid architecture diagram showing:
+- Frontend / client layer
+- Backend / API layer
+- Data stores and pipelines
+- Third-party integrations
+- Current AI/ML components (if any)
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        A[Web App] --> B[API Gateway]
+        C[Mobile App] --> B
+    end
+    subgraph "Backend"
+        B --> D[Application Server]
+        D --> E[Database]
+        D --> F[Cache]
+    end
+    subgraph "Data"
+        E --> G[ETL Pipeline]
+        G --> H[Data Warehouse]
+        H --> I[BI Dashboard]
+    end
+```
+
+Customize this template based on the client's actual stack.
+
+### 2c. Data Readiness Score
+
+Score the client 1-5 on each of the following five dimensions. Use the intake answers and apply professional judgment.
+
+| Dimension | 1 (Poor) | 2 (Basic) | 3 (Developing) | 4 (Strong) | 5 (Excellent) |
+|---|---|---|---|---|---|
+| **Volume** | Minimal data, mostly manual | Some digital records | Moderate structured data | Large structured datasets | Massive, diverse data assets |
+| **Quality** | No standards, high error rates | Ad hoc cleaning | Some validation rules | Systematic quality processes | Automated quality pipelines |
+| **Accessibility** | Data locked in silos | Some shared access | Central repository exists | Well-organized data catalog | Self-service data platform |
+| **Governance** | No policies | Informal practices | Some documented policies | Formal governance program | Mature governance with automation |
+| **Integration** | No integration | Manual exports/imports | Some API connections | Integrated data pipelines | Real-time unified data layer |
+
+Calculate composite Data Readiness Score = average of 5 dimensions (round to 1 decimal).
+
+### 2d. Team Capability Matrix
+
+Create a matrix of the client's team capabilities relevant to AI adoption:
+
+| Capability | Current Level | Gap to AI-Ready | Priority |
+|---|---|---|---|
+| Data Engineering | Low/Medium/High | Description of gap | High/Medium/Low |
+| ML/AI Development | Low/Medium/High | Description of gap | High/Medium/Low |
+| Data Science/Analytics | Low/Medium/High | Description of gap | High/Medium/Low |
+| Product Management (AI) | Low/Medium/High | Description of gap | High/Medium/Low |
+| Change Management | Low/Medium/High | Description of gap | High/Medium/Low |
+
+## Step 3 — AI Maturity Assessment
+
+Score the client 1-5 across five maturity dimensions using this rubric:
+
+### Maturity Scoring Rubric
+
+**Strategy (weight: 1x)**
+- 1: No AI strategy, no executive awareness
+- 2: Executive curiosity, no formal plan
+- 3: AI included in strategic discussions, informal roadmap
+- 4: Formal AI strategy with budget and governance
+- 5: AI-first culture, AI embedded in corporate strategy
+
+**Data (weight: 1x)**
+- 1: Siloed, inconsistent, no governance
+- 2: Some centralization, basic quality standards
+- 3: Data warehouse/lake in place, documented governance
+- 4: Integrated data platform, active data quality programs
+- 5: Real-time data fabric, self-service analytics, ML-ready pipelines
+
+**Technology (weight: 1x)**
+- 1: Legacy systems, no cloud, no ML infrastructure
+- 2: Some cloud adoption, basic APIs
+- 3: Cloud-native apps, CI/CD, some ML tooling
+- 4: MLOps platform, feature stores, model registry
+- 5: Full ML platform, automated retraining, edge deployment
+
+**People (weight: 1x)**
+- 1: No AI/ML skills in org
+- 2: 1-2 data analysts, no ML engineers
+- 3: Small data team, some ML experience
+- 4: Dedicated AI team with ML engineers and data scientists
+- 5: Distributed AI expertise, AI champions in every department
+
+**Process (weight: 1x)**
+- 1: No AI-related processes
+- 2: Ad hoc experimentation
+- 3: Defined ML development lifecycle
+- 4: Standardized MLOps, model monitoring, A/B testing
+- 5: Continuous AI improvement, automated model governance
+
+### Composite Score Calculation
+
+```
+Composite Score = Strategy + Data + Technology + People + Process
+Range: 5 to 25
+```
+
+### Readiness Level Mapping
+
+| Composite Score | Readiness Level | Description |
+|---|---|---|
+| 1-5 | Not Ready | Foundational gaps across all dimensions. Focus on data and strategy basics first. |
+| 6-10 | Early Stage | Some awareness and early efforts. Needs structured roadmap and capability building. |
+| 11-15 | Developing | Active efforts underway. Ready for targeted AI pilots with guided support. |
+| 16-20 | Advancing | Strong foundation in place. Ready for scaled AI deployment and advanced use cases. |
+| 21-25 | AI-Native Ready | Mature across all dimensions. Focus on optimization, innovation, and competitive moats. |
+
+Present scores as a radar chart description and a summary table:
+
+```
+AI Maturity Scorecard
+=====================
+Strategy:   [X] / 5  ████░░░░░░
+Data:       [X] / 5  ██████░░░░
+Technology: [X] / 5  ████████░░
+People:     [X] / 5  ██░░░░░░░░
+Process:    [X] / 5  ████░░░░░░
+
+Composite:  [XX] / 25
+Readiness:  [Level Name]
+```
+
+## Step 4 — Competitive Landscape Research
+
+Use WebSearch to research the competitive landscape. Execute the following searches:
+
+1. `"[industry] AI adoption trends 2025 2026"` — identify industry-wide AI trends
+2. `"[top competitor 1] artificial intelligence"` — specific competitor AI initiatives
+3. `"[top competitor 2] AI machine learning"` — second competitor if known
+4. `"[industry] AI case studies ROI"` — find relevant case studies with ROI data
+
+From the search results, compile:
+
+- **Industry AI Adoption Rate**: What percentage of peers are adopting AI?
+- **Competitor AI Initiatives**: What are direct competitors doing with AI?
+- **Relevant Case Studies**: 2-3 case studies from the industry with quantified results
+- **Emerging Opportunities**: AI applications gaining traction in this vertical
+- **Threats**: Risk of falling behind if AI is not adopted
+
+Summarize findings in a competitive intelligence brief (max 500 words).
+
+## Step 5 — Output Files
+
+Create the following files in the client's directory at `consulting-toolkit/clients/<client-name>/`:
+
+### 5a. `profile.md`
+
+Client profile summary containing:
+- Company name, industry, size, revenue range
+- Business model summary (from Step 2a)
+- Key contacts and stakeholders (if provided)
+- Engagement date
+- AI Maturity composite score and readiness level
+
+### 5b. `discovery/intake.md`
+
+Full intake interview record:
+- All 13 questions with verbatim answers
+- Any additional context provided
+- Date of intake
+
+### 5c. `discovery/current-state.md`
+
+Current state analysis containing:
+- Business model narrative (from Step 2a)
+- Tech stack Mermaid diagram (from Step 2b)
+- Data readiness scores table (from Step 2c)
+- Team capability matrix (from Step 2d)
+
+### 5d. `discovery/maturity-assessment.md`
+
+AI maturity assessment containing:
+- Individual dimension scores with justification
+- Composite score and readiness level
+- ASCII scorecard visualization
+- Key strengths and gaps identified
+- Recommended focus areas for improvement
+
+### 5e. `discovery/stakeholder-map.md`
+
+Stakeholder analysis containing:
+- Decision makers (who approves budget and strategy)
+- Influencers (who shapes technical direction)
+- Champions (who will drive adoption internally)
+- End users (who will use AI-powered tools)
+- Blockers (who may resist change and why)
+
+If stakeholder information was not provided during intake, create the template with placeholder sections and note that this should be filled in during follow-up conversations.
+
+## Notes
+
+- All output files use Markdown format
+- Mermaid diagrams should be valid and renderable
+- Scores should be justified with specific evidence from the intake
+- If the client directory already exists, warn the user and ask whether to overwrite or create a versioned copy
+- The entire discovery process should take 15-20 minutes with a cooperative client