aigent-team 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+
+declare const PLATFORMS: readonly ["claude-code", "cursor", "codex", "antigravity"];
+type Platform = (typeof PLATFORMS)[number];
+declare const TEAM_ROLES: readonly ["lead", "ba", "fe", "be", "qa", "devops"];
+type TeamRole = (typeof TEAM_ROLES)[number];
+interface ReferenceFile {
+    id: string;
+    title: string;
+    description: string;
+    whenToRead: string;
+    content: string;
+}
+interface TechStackConfig {
+    languages: string[];
+    frameworks: string[];
+    libraries: string[];
+    buildTools: string[];
+}
+interface ToolPermissions {
+    allowed: string[];
+    denied?: string[];
+}
+interface WorkflowDefinition {
+    name: string;
+    description: string;
+    steps: string[];
+}
+interface AgentDefinition {
+    id: string;
+    name: string;
+    description: string;
+    role: TeamRole;
+    systemPrompt: string;
+    skillContent: string;
+    techStack: TechStackConfig;
+    conventions: string;
+    reviewChecklist: string;
+    tools: ToolPermissions;
+    workflows: WorkflowDefinition[];
+    sharedKnowledge: string[];
+    references: ReferenceFile[];
+    globs?: string[];
+}
+declare const ConfigSchema: z.ZodObject<{
+    projectName: z.ZodString;
+    platforms: z.ZodArray<z.ZodEnum<["claude-code", "cursor", "codex", "antigravity"]>, "many">;
+    teams: z.ZodArray<z.ZodEnum<["lead", "ba", "fe", "be", "qa", "devops"]>, "many">;
+    overrides: z.ZodOptional<z.ZodRecord<z.ZodEnum<["lead", "ba", "fe", "be", "qa", "devops"]>, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        techStack: z.ZodOptional<z.ZodObject<{
+            languages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            frameworks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            libraries: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            buildTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            languages?: string[] | undefined;
+            frameworks?: string[] | undefined;
+            libraries?: string[] | undefined;
+            buildTools?: string[] | undefined;
+        }, {
+            languages?: string[] | undefined;
+            frameworks?: string[] | undefined;
+            libraries?: string[] | undefined;
+            buildTools?: string[] | undefined;
+        }>>;
+        conventions: z.ZodOptional<z.ZodString>;
+        reviewChecklist: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodObject<{
+            allowed: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            denied: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            allowed?: string[] | undefined;
+            denied?: string[] | undefined;
+        }, {
+            allowed?: string[] | undefined;
+            denied?: string[] | undefined;
+        }>>;
+        globs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string | undefined;
+        description?: string | undefined;
+        systemPrompt?: string | undefined;
+        techStack?: {
+            languages?: string[] | undefined;
+            frameworks?: string[] | undefined;
+            libraries?: string[] | undefined;
+            buildTools?: string[] | undefined;
+        } | undefined;
+        conventions?: string | undefined;
+        reviewChecklist?: string | undefined;
+        tools?: {
+            allowed?: string[] | undefined;
+            denied?: string[] | undefined;
+        } | undefined;
+        globs?: string[] | undefined;
+    }, {
+        name?: string | undefined;
+        description?: string | undefined;
+        systemPrompt?: string | undefined;
+        techStack?: {
+            languages?: string[] | undefined;
+            frameworks?: string[] | undefined;
+            libraries?: string[] | undefined;
+            buildTools?: string[] | undefined;
+        } | undefined;
+        conventions?: string | undefined;
+        reviewChecklist?: string | undefined;
+        tools?: {
+            allowed?: string[] | undefined;
+            denied?: string[] | undefined;
+        } | undefined;
+        globs?: string[] | undefined;
+    }>>>;
+    shared: z.ZodOptional<z.ZodObject<{
+        conventions: z.ZodOptional<z.ZodString>;
+        apiSpecs: z.ZodOptional<z.ZodString>;
+        architecture: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        conventions?: string | undefined;
+        apiSpecs?: string | undefined;
+        architecture?: string | undefined;
+    }, {
+        conventions?: string | undefined;
+        apiSpecs?: string | undefined;
+        architecture?: string | undefined;
+    }>>;
+    output: z.ZodOptional<z.ZodObject<{
+        directory: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        directory?: string | undefined;
+    }, {
+        directory?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    platforms: ("claude-code" | "cursor" | "codex" | "antigravity")[];
+    teams: ("lead" | "ba" | "fe" | "be" | "qa" | "devops")[];
+    overrides?: Partial<Record<"lead" | "ba" | "fe" | "be" | "qa" | "devops", {
+        name?: string | undefined;
+        description?: string | undefined;
+        systemPrompt?: string | undefined;
+        techStack?: {
+            languages?: string[] | undefined;
+            frameworks?: string[] | undefined;
+            libraries?: string[] | undefined;
+            buildTools?: string[] | undefined;
+        } | undefined;
+        conventions?: string | undefined;
+        reviewChecklist?: string | undefined;
+        tools?: {
+            allowed?: string[] | undefined;
+            denied?: string[] | undefined;
+        } | undefined;
+        globs?: string[] | undefined;
+    }>> | undefined;
+    shared?: {
+        conventions?: string | undefined;
+        apiSpecs?: string | undefined;
+        architecture?: string | undefined;
+    } | undefined;
+    output?: {
+        directory?: string | undefined;
+    } | undefined;
+}, {
+    projectName: string;
+    platforms: ("claude-code" | "cursor" | "codex" | "antigravity")[];
+    teams: ("lead" | "ba" | "fe" | "be" | "qa" | "devops")[];
+    overrides?: Partial<Record<"lead" | "ba" | "fe" | "be" | "qa" | "devops", {
+        name?: string | undefined;
+        description?: string | undefined;
+        systemPrompt?: string | undefined;
+        techStack?: {
+            languages?: string[] | undefined;
+            frameworks?: string[] | undefined;
+            libraries?: string[] | undefined;
+            buildTools?: string[] | undefined;
+        } | undefined;
+        conventions?: string | undefined;
+        reviewChecklist?: string | undefined;
+        tools?: {
+            allowed?: string[] | undefined;
+            denied?: string[] | undefined;
+        } | undefined;
+        globs?: string[] | undefined;
+    }>> | undefined;
+    shared?: {
+        conventions?: string | undefined;
+        apiSpecs?: string | undefined;
+        architecture?: string | undefined;
+    } | undefined;
+    output?: {
+        directory?: string | undefined;
+    } | undefined;
+}>;
+type AigentTeamConfig = z.infer<typeof ConfigSchema>;
+interface CompiledOutput {
+    filePath: string;
+    content: string;
+    overwriteStrategy: 'replace' | 'merge' | 'skip-if-exists';
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+
+declare function loadConfig(cwd?: string): Promise<AigentTeamConfig>;
+declare function configExists(cwd?: string): boolean;
+
+declare function loadAgents(config: AigentTeamConfig, cwd?: string): AgentDefinition[];
+
+/**
+ * Assemble the slim skill index for an agent (~150-200 lines).
+ * Used as the primary agent content that's always loaded.
+ * If agent has skillContent (from skill.md), use that directly.
+ * Otherwise, fall back to legacy assembly from parts.
+ */
+declare function assembleSkillIndex(agent: AgentDefinition): string;
+/**
+ * Legacy: assemble full agent markdown from all parts.
+ * Used when no skill.md exists.
+ */
+declare function assembleAgentMarkdown(agent: AgentDefinition): string;
+/**
+ * Format a single reference file for output.
+ */
+declare function assembleReference(ref: ReferenceFile): string;
+
+declare function defineConfig(config: AigentTeamConfig): AigentTeamConfig;
+
+export { type AgentDefinition, type AigentTeamConfig, type CompiledOutput, PLATFORMS, type Platform, type ReferenceFile, TEAM_ROLES, type TeamRole, type TechStackConfig, type ToolPermissions, type ValidationResult, type WorkflowDefinition, assembleAgentMarkdown, assembleReference, assembleSkillIndex, configExists, defineConfig, loadAgents, loadConfig };

package/dist/index.js

@@ -0,0 +1,27 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+import {
+  PLATFORMS,
+  TEAM_ROLES,
+  assembleAgentMarkdown,
+  assembleReference,
+  assembleSkillIndex,
+  configExists,
+  loadAgents,
+  loadConfig
+} from "./chunk-N3RYHWTR.js";
+
+// src/index.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  PLATFORMS,
+  TEAM_ROLES,
+  assembleAgentMarkdown,
+  assembleReference,
+  assembleSkillIndex,
+  configExists,
+  defineConfig,
+  loadAgents,
+  loadConfig
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "aigent-team",
+  "version": "0.1.0",
+  "description": "Cross-platform AI agent team plugin for Claude Code, Cursor, Codex, and Antigravity",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "aigent-team": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "cursor",
+    "codex",
+    "antigravity",
+    "cli"
+  ],
+  "author": "Đức Trần Xuân <ductranxuan.29710@gmail.com> (https://github.com/ducsatthu)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ducsatthu/aigent-team.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ducsatthu/aigent-team/issues"
+  },
+  "homepage": "https://github.com/ducsatthu/aigent-team#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "deepmerge-ts": "^7.1.5",
+    "glob": "^11.0.1",
+    "gray-matter": "^4.0.3",
+    "inquirer": "^12.4.0",
+    "yaml": "^2.7.1",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.1"
+  }
+}

package/templates/shared/git-workflow.md

@@ -0,0 +1,44 @@
+## Branch Strategy
+
+- **Main branch** (`main`): Always deployable. Protected — no direct pushes. All changes via PR.
+- **Feature branches**: `feat/{ticket-id}-{short-description}` — e.g., `feat/PROJ-123-add-oauth-login`
+- **Bug fix branches**: `fix/{ticket-id}-{short-description}` — e.g., `fix/PROJ-456-null-pointer-on-empty-cart`
+- **Other types**: `refactor/`, `docs/`, `test/`, `chore/`, `ci/`
+- **Hotfix**: `hotfix/{ticket-id}-{description}` — branches from the production tag, merges to main AND production.
+
+## Commit Standards
+
+- Follow Conventional Commits: `type(scope): description`
+  - `feat`: New functionality visible to users
+  - `fix`: Bug fix
+  - `refactor`: Code change that neither fixes a bug nor adds a feature
+  - `test`: Adding or modifying tests
+  - `docs`: Documentation only
+  - `chore`: Build process, tooling, dependency updates
+  - `ci`: CI/CD pipeline changes
+  - `perf`: Performance improvement
+- Description is imperative mood, lowercase, no period: `add login form` not `Added login form.`
+- Body (optional): explain **why**, not what. The diff shows what changed.
+- Breaking changes: add `!` after type — `feat(api)!: remove deprecated /v1/users endpoint`
+
+## Pull Request Process
+
+1. **Before opening PR**: Rebase on latest main. Run linter + tests locally. Self-review your own diff.
+2. **PR title**: Same as commit message format. Keep under 72 characters.
+3. **PR description must include**:
+   - **What**: Brief summary of the change (1-3 sentences)
+   - **Why**: Link to ticket/issue. Business context for the change.
+   - **How to test**: Step-by-step verification instructions. Include curl commands, screenshots, or test commands.
+   - **Breaking changes**: If any, describe migration steps.
+4. **Review requirements**: Minimum 1 approval. 2 approvals for: database migrations, auth changes, infrastructure, CI/CD, and changes touching >10 files.
+5. **Merge strategy**: Squash merge for feature branches (clean history). Merge commit for release branches (preserve individual commits).
+6. **Post-merge**: Delete the branch. Verify CI passes on main. Check staging deployment if auto-deployed.
+
+## Release Process
+
+- Semantic versioning: `MAJOR.MINOR.PATCH`
+  - MAJOR: Breaking API changes
+  - MINOR: New features, backward compatible
+  - PATCH: Bug fixes, backward compatible
+- Tag releases on main: `git tag -a v1.2.3 -m "Release v1.2.3"`
+- Changelog generated from conventional commit messages (using `standard-version` or `changesets`).

package/templates/shared/project-conventions.md

@@ -0,0 +1,48 @@
+## Naming Conventions
+
+- Variables/functions: `camelCase` (JS/TS), `snake_case` (Python/Go/Rust)
+- Types/classes/interfaces: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE` for true compile-time constants. Regular `camelCase` for runtime values that don't change.
+- File names: `kebab-case.ts` for modules, `PascalCase.tsx` for React components
+- Database tables: `snake_case` plural (`users`, `order_items`). Columns: `snake_case` singular.
+- API URLs: `kebab-case` (`/api/user-profiles`). Query params: `camelCase` or `snake_case` (be consistent).
+
+## Code Quality Rules
+
+- **Single responsibility**: Functions do one thing. If you can't name it without "and", split it.
+- **Early returns**: Validate preconditions at the top and return early. Avoid nested if-else pyramids:
+  ```typescript
+  // BAD
+  function process(user) {
+    if (user) {
+      if (user.active) {
+        // ...30 lines of logic
+      }
+    }
+  }
+  // GOOD
+  function process(user) {
+    if (!user) return;
+    if (!user.active) return;
+    // ...30 lines of logic
+  }
+  ```
+- **Explicit over implicit**: Named parameters over boolean flags. `createUser({ admin: true })` not `createUser(true)`.
+- **Error handling**: Handle errors explicitly at the point where you can do something useful about them. Don't catch at every level — let errors propagate to a handler that can provide meaningful feedback.
+- **No magic numbers/strings**: Extract to named constants. `const MAX_RETRY_ATTEMPTS = 3` not bare `3` in a loop.
+- **Dependencies**: Pin exact versions in lockfiles. Audit dependencies quarterly — remove unused, update vulnerable.
+- **Environment config**: All environment-specific values via environment variables. Use a typed config module that validates at startup (fail fast, not on first use).
+
+## Code Review Standards
+
+- Review for correctness first, then maintainability, then style. Don't bikeshed formatting — that's the linter's job.
+- Every PR must answer: what changed, why, and how to verify. If the reviewer can't understand the "why", the PR description needs work.
+- Look for what's NOT there: missing error handling, missing tests, missing logging, missing edge cases.
+- Large PRs (>500 lines changed) should be broken into smaller, reviewable chunks. Exception: mechanical refactors (renames, moves) where the diff is large but the change is simple.
+
+## Git Hygiene
+
+- Commit messages: `type(scope): description` — e.g., `feat(auth): add OAuth2 login flow`
+- Atomic commits: each commit compiles and passes tests. Don't commit broken intermediate states.
+- Rebase feature branches on main before merging. Resolve conflicts locally, not in the merge commit.
+- Delete merged branches immediately. Stale branches are noise.

package/templates/teams/ba/agent.yaml

@@ -0,0 +1,25 @@
+id: ba
+name: BA Agent
+description: >
+  Business Analyst agent. Translates business requirements into technical specs,
+  acceptance criteria, user stories, API contracts, and data flow diagrams.
+role: ba
+techStack:
+  languages: [Markdown, YAML, JSON]
+  frameworks: []
+  libraries: [Mermaid, OpenAPI]
+  buildTools: []
+tools:
+  allowed: [Read, Write, Edit, Grep, Glob]
+globs:
+  - "docs/**/*"
+  - "specs/**/*"
+  - "requirements/**/*"
+  - "**/*.md"
+  - "**/*.yaml"
+  - "**/*.yml"
+  - "openapi.*"
+  - "swagger.*"
+sharedKnowledge:
+  - project-conventions
+  - git-workflow

package/templates/teams/ba/references/acceptance-criteria.md

@@ -0,0 +1,87 @@
+# Writing Acceptance Criteria
+
+## Format: Given / When / Then
+
+```
+GIVEN [precondition — the state of the world before the action]
+WHEN [action — what the user does]
+THEN [expected outcome — what should happen]
+AND [additional outcomes if needed]
+```
+
+## Rules for Good Acceptance Criteria
+
+1. **Testable**: QA must be able to write an automated test from this criterion alone
+   - BAD: "The form should be user-friendly"
+   - GOOD: "GIVEN an empty form WHEN user submits THEN inline errors appear below each required field"
+
+2. **Specific**: Include exact values, behaviors, and states
+   - BAD: "The page loads quickly"
+   - GOOD: "GIVEN a list of 1000 items WHEN user loads the page THEN first 20 items render within 2 seconds"
+
+3. **Independent**: Each criterion should be verifiable on its own
+
+4. **Complete**: Cover happy path AND failure paths AND edge cases
+
+## Coverage Checklist
+
+For every user story, write criteria covering:
+
+- [ ] **Happy path**: Normal successful flow
+- [ ] **Validation errors**: What happens with invalid input?
+- [ ] **Authentication**: What if user is not logged in?
+- [ ] **Authorization**: What if user doesn't have permission?
+- [ ] **Empty state**: What if there's no data to display?
+- [ ] **Error state**: What if the server returns an error?
+- [ ] **Loading state**: What does the user see while waiting?
+- [ ] **Boundary values**: Minimum, maximum, empty string, very long text
+- [ ] **Concurrent action**: What if the same action happens simultaneously?
+
+## Example: User Registration
+
+```
+Story: As a new user, I want to register an account so I can access the platform.
+
+AC1: Successful registration
+GIVEN I am on the registration page
+WHEN I enter a valid email, password (8+ chars, 1 uppercase, 1 number), and name
+AND I click "Register"
+THEN my account is created
+AND I receive a verification email within 60 seconds
+AND I am redirected to the "check your email" page
+
+AC2: Duplicate email
+GIVEN a user with email "existing@example.com" already exists
+WHEN I enter "existing@example.com" and a valid password
+AND I click "Register"
+THEN I see an error "An account with this email already exists"
+AND a "Sign in" link is shown
+
+AC3: Weak password
+GIVEN I am on the registration page
+WHEN I enter a password shorter than 8 characters
+AND I move focus away from the password field (blur)
+THEN I see inline error "Password must be at least 8 characters"
+AND the submit button remains enabled (errors shown inline, not blocking)
+
+AC4: Email format validation
+GIVEN I am on the registration page
+WHEN I enter "not-an-email" in the email field
+AND I move focus away (blur)
+THEN I see inline error "Please enter a valid email address"
+
+AC5: Empty form submission
+GIVEN I am on the registration page with all fields empty
+WHEN I click "Register"
+THEN inline errors appear below each required field
+AND focus moves to the first field with an error
+AND the page does NOT scroll to top or show a toast
+```
+
+## Anti-patterns
+
+- **Vague criteria**: "System should handle errors gracefully" — which errors? What does "gracefully" mean?
+- **Implementation details**: "System stores user in PostgreSQL users table" — that's a design decision, not a requirement
+- **Untestable**: "System should be fast" — what's "fast"? Specify response time targets.
+- **Missing negative cases**: Only happy path criteria = bugs in production from unhandled edge cases
+- **Ambiguous pronouns**: "It should display the message" — which message? To whom?

package/templates/teams/ba/references/api-contract-design.md

@@ -0,0 +1,110 @@
+# API Contract Design
+
+## Purpose
+
+An API contract is the agreement between FE and BE about how they communicate. It must be defined BEFORE implementation starts so both can work in parallel against the same spec.
+
+## Contract Template
+
+```yaml
+# Endpoint: Create Order
+method: POST
+path: /api/v1/orders
+auth: required (role: user)
+rate_limit: 30/min per user
+
+request:
+  headers:
+    Content-Type: application/json
+    Authorization: Bearer {access_token}
+  body:
+    productId:
+      type: string
+      required: true
+      example: "prod_abc123"
+    quantity:
+      type: integer
+      required: true
+      min: 1
+      max: 100
+    couponCode:
+      type: string
+      required: false
+      maxLength: 20
+      example: "SAVE10"
+
+response:
+  201 Created:
+    description: Order created successfully
+    body:
+      data:
+        id: string (e.g., "ord_xyz789")
+        productId: string
+        quantity: integer
+        unitPrice: integer (cents)
+        discount: integer (cents)
+        total: integer (cents)
+        status: "pending" | "confirmed" | "shipped"
+        createdAt: string (ISO 8601)
+
+  400 Bad Request:
+    description: Validation error
+    body:
+      error:
+        code: "VALIDATION_ERROR"
+        message: string
+        details:
+          - field: string
+            message: string
+
+  401 Unauthorized:
+    body:
+      error:
+        code: "UNAUTHORIZED"
+        message: "Authentication required"
+
+  404 Not Found:
+    description: Product not found
+    body:
+      error:
+        code: "PRODUCT_NOT_FOUND"
+        message: "Product {productId} does not exist"
+
+  409 Conflict:
+    description: Insufficient stock
+    body:
+      error:
+        code: "INSUFFICIENT_STOCK"
+        message: "Only {available} units available"
+```
+
+## Design Principles
+
+1. **BE owns the data model, FE drives the API shape** — FE knows what it needs to render, BE knows how to store/compute it. Meet in the middle.
+
+2. **Response includes everything FE needs** — FE should not make N requests to assemble one view. If a list page needs user name + avatar, include them in the list response.
+
+3. **Consistent patterns across endpoints** — same pagination format, same error format, same date format everywhere.
+
+4. **Version from day one** — `/v1/` prefix. Even if you never make v2, it costs nothing and saves you later.
+
+5. **Error codes are machine-readable** — FE switches on `error.code` (not `error.message`) to decide what to show the user.
+
+## Review Checklist
+
+Before finalizing a contract, verify:
+- [ ] All FE views can be rendered with the data in the response
+- [ ] All user actions have a corresponding endpoint
+- [ ] Error responses cover all failure modes (validation, auth, not-found, conflict)
+- [ ] Pagination included for list endpoints
+- [ ] Sorting and filtering params defined
+- [ ] Response includes `id` for every entity (for FE to use as key/link)
+- [ ] Date/time fields are ISO 8601 strings
+- [ ] Money fields are integers in smallest unit (cents)
+- [ ] Consistent naming (camelCase for JSON, snake_case only if project convention)
+
+## Contract Evolution
+
+- **Non-breaking** (no version bump needed): add optional request field, add response field, add new endpoint
+- **Breaking** (requires v2): remove/rename field, change field type, add required request field, change URL
+- **Migration path**: support v1 and v2 simultaneously for 3 months, then deprecate v1