feat: add bq-assess CLI + skill under solution-architecture/clis

[jingchaoyy]

Problem

Startups and enterprises increasingly want to move analytics workloads off Google BigQuery to an AWS lakehouse — but before they'll commit, they need to know two things: how much it will cost and how much work it will be. Today there's no AWS-native way to answer either up front.

AWS SCT supports BigQuery as a source, but it can't convert the nested constructs (STRUCT, ARRAY, UNNEST) that modern BigQuery warehouses are built on, and it produces no cost comparison — the single most important input to a customer's decision. That leaves AWS teams reliant on partner accelerators or weeks of manual, per-table analysis across environments that routinely hold tens of thousands of tables. The result: slow, inconsistent assessments that stall deals at the qualification stage.

Solution

bq-assess closes that gap. A read-only scan of a customer's BigQuery environment produces a per-table migration plan scored on two independent axes — Migration Effort (moving the data) and Query Complexity (rewriting the SQL) — plus generated Iceberg DDL and a directional cost comparison. It turns a multi-week manual effort into a minutes-long, reproducible assessment, giving customers a credible plan and AWS teams a data-backed starting point for the migration conversation.

Ships under a new solution-architecture/clis/ subfolder as a full Python CLI plus a guided Claude Code skill. The scan needs only roles/bigquery.metadataViewer (reads no table data), targets S3 Tables (Apache Iceberg) storage with Amazon Redshift compute, and requires no AWS account to run. It assesses only; it does not execute the migration. Two run modes: direct (bq-assess), or collect-then-report (bq-collect writes a reviewable plain-JSON bundle; bq-assess report renders it offline anywhere).

What's included

• solution-architecture/clis/bq-assess/ — the tool
  • src/, tests/ (479 unit + property-based tests), pyproject.toml, LICENSE (Apache-2.0)
  • skills/bq-assess/ — Claude Code skill (preflight → scan → interpret state machine)
  • .claude-plugin/plugin.json, README.md, PRIVACY.md
  • docs/ — CLI reference, complexity scoring guide, 4 ADRs
  • bandit.yml — plugin-scoped skips (B101/B608) with documented reasoning, following the ai-to-aws pattern
• Root .claude-plugin/marketplace.json — new bq-assess entry
• Root README.md — plugins table row + repository structure tree
• mise.toml + .github/workflows/security-scanners.yml — bandit extended from two-pass to three-pass so this plugin scans with its own config (exact same mechanism as ai-to-aws)

Validation

• mise run build passes locally — all stages green: lint:md (0 errors), fmt:check, bandit (0 issues across all three passes), semgrep, gitleaks (no leaks; also run in dir mode over the working tree), checkov (160 passed / 0 failed), grype (no vulnerabilities)
• 479 pytest pass; the plugin's tests/plugin/structure.sh passes (updated for the new layout, with a stricter no-internal-hostnames check — zero exceptions)
• Both install paths tested end-to-end from this fork: pip install "git+…#subdirectory=solution-architecture/clis/bq-assess" in a clean venv (both entry points run, report templates ship in the wheel), and claude plugin marketplace add → claude plugin install bq-assess@startups-for-aws → skill discovered (1 skill, ~180 always-on tokens)
• claude plugin validate passes on the plugin manifest and the marketplace manifest
• The tool has been run against three customer BigQuery environments during live migration engagements and five internal test environments

Type of Change

• New plugin/power/tool

Team Folder

• advisor/
• migrate/
• Other: solution-architecture/ (existing folder, new clis/ subfolder)

⚠️ Admin approval required

Per CODEOWNERS, this PR touches admin-gated paths and needs @awslabs/startups-admins review in addition to @awslabs/startups-solution-architects:

• **/.claude-plugin/ — new plugin manifest and root marketplace.json
• **/SKILL.md — the skill
• /.github/ — the three-pass bandit extension in security-scanners.yml
• mise.toml

Checklist

• I have read the CONTRIBUTING.md guidelines
• My changes do not include hardcoded secrets, credentials, or internal-only content
• I have run mise run build locally and it passes
• I have updated documentation if needed
• My changes are scoped to my team's folder only (plus the root marketplace/README/mise/CI wiring required to register a new plugin with Python code)

[rsmets]

Thanks for putting this together, and for the thoroughness. The underlying cli tool clearly solves a real problem. My comments are about packaging and placement rather than the tool itself, and I think a couple of adjustments would make this land much more cleanly in the repo.

1. "Plugin" and "skill" are being used interchangeably, and they're different things.
   A Claude Code plugin is the distributable unit registered in marketplace.json; a skill is a component that lives inside a plugin (alongside agents, MCP servers, etc.). The repo already models this well: aws-dev-toolkit is one plugin containing 35 skills. In this PR the marketplace.json entry, plugin.json, and the PR title ("CLI + skill") blur the two: we're registering a plugin (bq-assess) that happens to contain a single skill, but the framing describes it as a skill. Worth aligning the language so installers and future contributors aren't confused about what they're adding.

2. Consider hosting the CLI in its own repo, and keeping only the skill/agent here.
   This adds ~25k lines dominated by a standalone Python CLI with its own packaging and wheels, a heavier, differently shaped artifact than the guidance-oriented plugins this repo is built around (which orchestrate work via skills and agents rather than bundling a full application). A cleaner split, and one that matches how migration-to-aws and ai-to-aws are structured:

• Publish the bq-assess CLI in a dedicated awslabs/ (and/or PyPI), where it can version, release, and be security-scanned on its own cadence.
• Contribute here only a lightweight skill/agent that guides the user through installing and running that CLI and interpreting results, the same "skill drives the tool" pattern the repo already uses. @lralic4's latest contribution did something similar.

This keeps awslabs/startups focused on the Claude Code plugin surface, avoids a 25k-line standalone app in the marketplace repo, and lets the CLI evolve independently. It also directly answers the open question you raised in #132 about the preferred home.