Port import skill to MCP-first conventions

README.md

@@ -2,7 +2,7 @@
 
 Build infrastructure bundles for [Massdriver](https://massdriver.cloud) — the internal developer platform that turns infrastructure-as-code into reusable, self-service components with built-in guardrails.
 
-This plugin is **MCP-first**: all control-plane operations (projects, environments, components, deployments, resources) go through the [Massdriver MCP server](https://github.com/massdriver-cloud/mcp-server), which the plugin registers automatically. The **Massdriver CLI** (`mass`) is still required for filesystem-bound work — bundle build/lint/publish/pull and resource-type publishing.
+Describe what you want, and Claude designs the bundle, deploys it to a throwaway environment, and iterates until it's working and compliant. It drives Massdriver through the [MCP server](https://github.com/massdriver-cloud/mcp-server), which the plugin registers for you — that's why Docker is a prerequisite alongside the `mass` CLI.
 
 ## Installation
 
@@ -56,12 +56,12 @@ Interactive workflow for creating and testing bundles with deploy loop and compl
 **What it does:**
 1. Gathers your design intent (UX, constraints, connections)
 2. Scaffolds the bundle with best practices
-3. Sets up project + ephemeral test environment (MCP `create_project` / `create_environment`)
-4. Adds the bundle as a component in the project's blueprint (MCP `add_component`)
-5. Pins the test instance to the development channel (MCP `update_instance`, version `latest+dev`)
-6. Runs deploy loop: MCP `create_deployment` + `get_deployment_logs follow:true`, republishing via CLI as code changes
+3. Sets up a project and an ephemeral test environment
+4. Adds the bundle to the project's blueprint, so every environment gets an instance
+5. Deploys it, streaming the logs as they happen
+6. Iterates: code change → republish → redeploy, until it works
 7. Remediates compliance findings automatically
-8. Journals results in the environment description (MCP `update_environment`)
+8. Tears the infrastructure down, then journals what was tested on the environment
 
 ### `/massdriver:test-upgrade` - Day 2 Upgrade Testing
 
@@ -74,11 +74,11 @@ Validate bundle version upgrades by forking the production environment and copyi
 Instance identifier format `{project}-{environment}-{component}`.
 
 **What it does:**
-1. Forks the source instance's environment with `fork_environment`, carrying prod's component config (secrets/remote refs/env defaults opt-in)
-2. Verifies the mirror with `compare_environments`, low-scaling non-critical dependencies via `copy_instance` overrides
-3. Deploys the current version as a baseline (`create_deployment`)
-4. Bumps the version (`update_instance`), redeploys, and audits the change with `compare_deployments`
-5. Reports success/failure with recommendations (including `rollback_deployment` as the day-2 escape hatch), then tears down with `decommission_environment`
+1. Forks production into a test environment, carrying its config across (secrets, remote references, and environment defaults are opt-in)
+2. Diffs the fork against prod to confirm it's a faithful mirror, low-scaling any dependencies that don't need to match
+3. Deploys the current version as a baseline
+4. Bumps to the target version, redeploys, and reports exactly what changed — bundle version and param-level diff
+5. Tells you whether the upgrade is safe to roll out, then tears the test environment down
 
 ### `/massdriver:gen` - Quick Scaffolding
 
@@ -88,7 +88,36 @@ Generate a bundle without the deploy loop.
 /massdriver:gen RDS MySQL for OLTP workloads
 ```
 
-### `/massdriver:architect` - Citizen Engineer App Design (experimental)
+### `/massdriver:import` - Import Existing Cloud Resources
+
+Bring cloud infrastructure that already exists (created by hand, by another IaC tool, or in
+another account) under Massdriver. The command asks **how** you want to import, then the agent
+runs the matching workflow.
+
+```
+/massdriver:import existing production RDS Postgres instance created by hand
+```
+
+**Three paths (you choose up front):**
+1. **New bundle** — author a new reusable bundle, publish it, add it to the blueprint, then
+   `tofu import` the resource into that instance's managed state.
+2. **Existing bundle** — reuse a published bundle, create/pick an undeployed instance, then
+   import into its managed state.
+3. **Register resource only** — create an `EXTERNAL` Massdriver resource so other components can
+   connect to it, with no IaC and no lifecycle management.
+
+Paths 1 and 2 put the resource under Massdriver's IaC management; path 3 only makes it
+referenceable. Bundles have to stay reusable, so adoption uses the imperative `tofu import`
+command against the instance's Massdriver-managed HTTP state backend — **not `import {}`
+blocks**, which would hardcode one cloud resource ID into source shared by every instance. The
+import runs locally, but the plan runs in Massdriver's provisioner — never `tofu plan` locally,
+where credentials and compliance checks don't apply. The agent loops import → publish → re-plan
+until the plan comes back clean, before anything is deployed.
+
+> Not to be confused with `mass bundle import`, which scans a bundle's IaC for variables not yet
+> exposed as Massdriver params.
+
+### `/massdriver:architect` - Citizen Developer App Design (experimental)
 
 Turn a plain-language app idea into a governed Massdriver project: the agent probes the
 (grant-filtered) platform catalog, recommends project layout/bundles/runtime (decisively — it
@@ -103,23 +132,21 @@ of improvising infrastructure.
 
 ## How It Works
 
-The plugin drives the Massdriver control plane through the official MCP server (100 tools):
-
-- **Deploys**: `create_deployment` (`PROVISION`/`PLAN`/`DECOMMISSION`) + `get_deployment_logs` with `follow: true`. Params travel with each deployment call.
-- **Blueprint composition**: `add_component` / `link_components` — components are added once at the project level; every environment auto-gets an instance.
-- **Day 2 operations**: deployment approval flow (`propose_deployment` → human approves), `rollback_deployment`, `plan_deployment`, `compare_environments`, `compare_deployments`, instance secrets, remote references.
-- **Release channels ride the version constraint**: `latest+dev` / `~1+dev` accept development releases; `latest` / `~1` are stable-only.
-- **Environment-scale operations**: `fork_environment` (test envs from prod), `deploy_environment` / `decommission_environment` (whole-environment waves in dependency order), `copy_instance` (config mirroring with overrides).
-- **The CLI handles filesystem work**: `mass bundle build|lint|new|publish|pull`, `mass resource-type publish|get|list`, and `mass server`.
+- **Design once, deploy everywhere.** A component is added to a project's blueprint one time; every environment automatically gets an instance of it. Wire one component's output to another's input and the connection follows into each environment.
+- **Deploy and watch in one step.** Every deploy streams its logs back, so Claude sees failures and Checkov findings as they happen and can act on them without you relaying output.
+- **Dry runs are always safe.** Plans never touch infrastructure and are allowed anywhere, including production — so Claude can check its work before proposing a change.
+- **Development releases stay out of everyone's way.** Publishing with `--development` and pinning a test instance to `latest+dev` means your iteration never reaches instances on stable.
+- **Day 2 is covered.** Fork production into a test environment, upgrade it, diff the result, and roll back if it regresses. Changes that need sign-off can be *proposed* instead of applied, for a human to approve.
+- **Environment-scale operations.** Deploy or decommission a whole environment in dependency order, or mirror one instance's config onto another with overrides.
 
 ## What This Plugin Does
 
 This plugin helps platform engineers create and test Massdriver bundles — reusable IaC modules that package OpenTofu, Terraform, or Helm with input schemas, resource type contracts, and operational policies.
 
 **Capabilities:**
-- **MCP-native operations**: Auto-registers the Massdriver MCP server; all control-plane work uses typed tools instead of shelling out
 - **Interactive development**: Full deploy loop with compliance remediation
-- **Upgrade testing**: Validate version upgrades against production configs (`fork_environment` + `copy_instance`, verified with `compare_environments`)
+- **Brownfield import**: Adopt cloud resources that already exist into bundles, or register them so other components can connect to them
+- **Upgrade testing**: Validate version upgrades against a faithful copy of your production config before rolling them out
 - **Safety guardrails**: Blocks non-development publishes and production-targeting writes — across BOTH `mass` CLI commands and MCP tool calls, including automated deployment approval
 - **Compliance automation**: Iterates until Checkov findings are resolved
 - **GraphQL reference**: Multi-entity queries for when one query beats a chain of tool calls
@@ -147,12 +174,14 @@ claude-plugins/
     │   ├── massdriver-safety-check.sh  # Deterministic PreToolUse guard (CLI + MCP)
     │   └── test-safety-check.sh    # Test suite for the safety guard
     ├── agents/
-    │   ├── architect.md            # Citizen-engineer project design (experimental)
+    │   ├── architect.md            # Citizen-developer project design (experimental)
     │   ├── bundle-dev.md           # Full development workflow
+    │   ├── resource-import.md      # Import existing cloud resources
     │   └── upgrade-tester.md       # Day 2 upgrade testing
     ├── commands/
     │   ├── architect.md            # /massdriver:architect
     │   ├── develop.md              # /massdriver:develop
+    │   ├── import.md               # /massdriver:import
     │   ├── test-upgrade.md         # /massdriver:test-upgrade
     │   └── gen.md                  # /massdriver:gen
     ├── hooks/
@@ -167,7 +196,8 @@ claude-plugins/
             └── references/
                 ├── graphql.md      # GraphQL multi-entity queries
                 ├── alarms.md       # AWS/GCP/Azure monitoring
-                └── compliance.md   # Checkov remediation
+                ├── compliance.md   # Checkov remediation
+                └── import.md       # Importing existing cloud resources
 ```
 
 ## Safety Guardrails

massdriver/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "massdriver",
   "description": "Ship your own cloud infrastructure without filing a ticket. Engineers through vibe coders describe what their app needs, and Massdriver provisions it from the modules your platform team already approved, with cost, security, and compliance policy enforced on every deploy.",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "author": {
     "name": "Massdriver",
     "url": "https://massdriver.cloud"
@@ -27,6 +27,8 @@
   "hosting",
   "environments",
   "preview-environments",
+  "import",
+  "brownfield",
   "massdriver"
 ]
 }

massdriver/agents/architect.md

@@ -1,7 +1,7 @@
 ---
 name: architect
 description: >-
-  Massdriver solutions architect for "citizen engineers." Takes an app idea (often described
+  Massdriver solutions architect for "citizen developers." Takes an app idea (often described
   in plain language, no infra background) and designs a real project on the platform: project
   layout and sharding, environment defaults and remote references, bundle recommendations (reuse
   org bundles, or build a custom application bundle), runtime selection, and a permission-gated
@@ -16,7 +16,7 @@ whenToUse: |
   user: "I want to stand up a WordPress site for the marketing team"
   assistant: "I'll use the architect agent to design a project for this — layout, bundles, runtime, and how it promotes to prod."
   <commentary>
-  App idea from a citizen engineer that needs to become governed infrastructure triggers this agent.
+  App idea from a citizen developer that needs to become governed infrastructure triggers this agent.
   </commentary>
   </example>
 
@@ -47,7 +47,7 @@ You are a Massdriver **solutions architect**. Where the `bundle-dev` agent build
 bundle, you design the whole **project**: how it's laid out, which bundles fill it, how
 environments default and reference each other, and how work promotes from dev to prod.
 
-Your user is often a **citizen engineer** — someone shipping an app with the help of an LLM who
+Your user is often a **citizen developer** — someone shipping an app with the help of an LLM who
 should *not* have to think in Terraform, IAM, or VPCs. Your job is to catch that work early and
 turn it into governed infrastructure: it lands in the org's cloud account, on
 secure/compliant/correct bundles, inside a visual, audit-trailed environment — never as an
@@ -69,7 +69,7 @@ UI step is needed, give the user clear instructions (with a `get_url` deep link)
 
 - Say **resource** and **resource type** in all prose — never "artifact." The only place that
   word appears is the literal `artifacts:` YAML key when writing `massdriver.yaml`.
-- Distinguish the two "reuse" verbs — they are different actions and citizen engineers conflate
+- Distinguish the two "reuse" verbs — they are different actions and citizen developers conflate
   them:
   - **Instantiate a catalog bundle**: add an approved bundle as a NEW dedicated component in the
     app's project (a new database, owned by this app).
@@ -124,7 +124,7 @@ runtime) — your recommendations should match how this org already operates.
 
 ## Phase 2: Understand the Use Case
 
-Get the citizen engineer's intent in plain language:
+Get the citizen developer's intent in plain language:
 
 - What is the app? Who uses it? What does "working" look like?
 - Is it stateless (web/API), stateful (needs a DB/cache), or event-driven (jobs/queues)?
@@ -143,7 +143,7 @@ Split into multiple projects when lifecycles or owners diverge:
 
 - **Foundational** (network, registry, DNS — rarely changes, org-shared) → its own project,
   consumed elsewhere via **remote references**.
-- **App/compute** (the thing the citizen engineer is shipping — changes constantly) → the app
+- **App/compute** (the thing the citizen developer is shipping — changes constantly) → the app
   project. Stateful dependencies owned by this app (its database, its queue) are components in
   the app's project, instantiated from catalog bundles.
 
@@ -155,7 +155,7 @@ Rule of thumb: *"If I delete this project, what should disappear with it?"*
 
 ### Environment defaults
 Recommend which resource types are set as environment defaults (cloud credentials, shared
-network/registry) so every instance in the env auto-wires them without the citizen engineer
+network/registry) so every instance in the env auto-wires them without the citizen developer
 configuring anything.
 
 ### Remote references (cross-project sharing)
@@ -170,7 +170,7 @@ across them, and which environments will exist.
 
 Choose how the app actually runs — **decisively**. By now you know the use case (Phase 2) and
 what the org offers (Phase 1). Do NOT ask the user to pick a runtime or confirm your choice —
-runtime selection is exactly the expertise you're supplying to a citizen engineer. Decide, state
+runtime selection is exactly the expertise you're supplying to a citizen developer. Decide, state
 your reasoning in one breath, and keep moving:
 
 > "Given the use case, you have **Lambda** or **Kubernetes** deployments available. Kubernetes
@@ -205,7 +205,7 @@ Terminology):
    already published, added as dedicated components in the app's project.
 2. **Remote-reference deployed resources** for org-shared infrastructure that already runs in
    another project (network, cluster, registry). Never re-create these.
-3. **Build a custom application bundle** — ONLY for the app-specific compute the citizen engineer
+3. **Build a custom application bundle** — ONLY for the app-specific compute the citizen developer
    is shipping (e.g. the serverless image resizer). **NEVER** build stateful or foundational
    infrastructure bundles (databases, caches, queues, networks, registries, orchestrators) to
    fill a catalog gap — that is exactly the ungoverned infrastructure this workflow exists to
@@ -257,11 +257,11 @@ development releases with `update_instance` (version `latest+dev` — the channe
 version constraint).
 
 The bundle lives on the platform, versioned and audit-tracked, without ever needing a remote git
-repo the citizen engineer can't push to.
+repo the citizen developer can't push to.
 
 ### Local git — always; remote — optional
 The platform is the source of truth for what's deployed, but the **source still deserves version
-control locally**. Do this automatically so the citizen engineer gets it for free:
+control locally**. Do this automatically so the citizen developer gets it for free:
 
 ```bash
 # If the working dir isn't already a git repo, initialize one — no remote required
@@ -270,7 +270,7 @@ git add -A
 git commit -m "architect: <app> scaffold — <project>/<component> (<runtime>)"
 ```
 
-- **Local commit is mandatory and requires no remote.** A citizen engineer with only Claude, the
+- **Local commit is mandatory and requires no remote.** A citizen developer with only Claude, the
   plugin, and cloud access can get fully version-controlled infrastructure without ever
   configuring git hosting.
 - **A remote is opt-in.** If the working dir *already has* a remote (`git remote -v`), ASK before