@austinchen705/chatbot-intg-skill 1.0.1

package/README.md

@@ -0,0 +1,137 @@
+# @austinchen705/chatbot-intg-skill
+
+An AI skill installer for **Claude Code**, **Codex**, and **Gemini** that guides vendors through complete AI Chatbot API integration — covering auth, chat lifecycle, escalation handling, error resilience, analysis, and debugging.
+
+## Install
+
+Run directly with `npx` (no install required):
+
+```bash
+npx @austinchen705/chatbot-intg-skill
+```
+
+Or install globally:
+
+```bash
+npm install -g @austinchen705/chatbot-intg-skill
+chatbot-intg-skill
+```
+
+## Usage
+
+### Interactive (default)
+
+```bash
+npx @austinchen705/chatbot-intg-skill
+```
+
+The installer will prompt you to select the target AI coding tool:
+
+```
+  AI Chatbot Integration Skill Installer
+  =======================================
+
+  Install for which tools? (comma-separated)
+  1) claude  2) codex  3) gemini  4) all
+  >
+```
+
+### Non-interactive (CI / scripted)
+
+Use the `--tool` flag to skip the prompt:
+
+```bash
+# Single tool
+npx @austinchen705/chatbot-intg-skill --tool claude
+
+# Multiple tools
+npx @austinchen705/chatbot-intg-skill --tool claude,codex
+
+# All tools
+npx @austinchen705/chatbot-intg-skill --tool all
+```
+
+## What Gets Installed
+
+| Tool | Skill files | Command / Instruction file |
+|------|-------------|---------------------------|
+| Claude Code | `.claude/skills/chatbot-intg/` | `.claude/commands/chatbot-intg.md` |
+| Codex | `.codex/skills/chatbot-intg/` | `.codex/AGENTS.md` (manual step) |
+| Gemini | `.gemini/skills/chatbot-intg/` | `.gemini/GEMINI.md` (manual step) |
+
+### Installed files
+
+```
+SKILL.md                          # Phased integration workflow
+resources/
+  chatbot_integration_spec.pdf    # API spec reference (v0.7)
+  integration-playbook.md         # Language-specific code templates
+```
+
+## Invoking the Skill
+
+**Claude Code** — the command is auto-detected after install:
+
+```
+/chatbot-intg
+```
+
+**Codex** — add the following line to `.codex/AGENTS.md`:
+
+```
+Read .codex/skills/chatbot-intg/SKILL.md for vendor integration workflow
+```
+
+**Gemini** — add the following line to `.gemini/GEMINI.md`:
+
+```
+Read .gemini/skills/chatbot-intg/SKILL.md for vendor integration workflow
+```
+
+## Integration Workflow
+
+The skill guides vendors through **6 gated phases**, each requiring user confirmation before proceeding:
+
+```
+Phase 0: Infrastructure       Language + framework + logging setup
+    ↓ (confirm)
+Phase 1: Auth & Connectivity  JWT token lifecycle + auto-refresh
+    ↓ (confirm)
+Phase 2: Core Chat Flow       Session dispatch → send loop → kickout + escalation
+    ↓ (confirm)
+Phase 3: Error Handling       Unified error framework + retry + circuit breaker
+    ↓ (confirm)
+Phase 4: Advanced (optional)  Chat Analysis + MCP Server guide
+    ↓ (confirm)
+Phase 5: Acceptance           Integration test checklist + debug handbook
+```
+
+### Supported Languages
+
+- Python (FastAPI / Django · httpx / requests · tenacity)
+- Java (Spring Boot · OkHttp / RestTemplate · Resilience4j)
+- C# (ASP.NET Core · HttpClient · Polly)
+- Node.js (Express / NestJS · axios · cockatiel)
+
+### Covered APIs
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| POST | `/api/v1/auth` | Obtain JWT Token |
+| POST | `/api/v1/chatbot/dispatch` | Create chat session |
+| GET | `/api/v1/chatbot/usage` | Query quota |
+| POST | `/api/v1/chatbot/kickout` | Close a session |
+| POST | `/api/v1/chatbot/killall` | Close all sessions |
+| POST | `/api/v1/chat/send` | Send message + receive AI response |
+| GET | `/api/v1/chat/history/{sessionId}` | Retrieve chat history |
+| POST | `/api/v1/analysis/create` | Submit conversation for analysis |
+| GET | `/api/v1/analysis/{sessionId}` | Poll analysis result |
+
+## Requirements
+
+- Node.js >= 14
+- Run from the **root of your project** so skill files land in the right directories
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const TARGETS = {
+  claude: {
+    skillDir: '.claude/skills/chatbot-intg',
+    commandDir: '.claude/commands',
+    commandFile: 'chatbot-intg.md',
+    instructionFile: null,
+    postInstall: '  Claude Code: skill auto-detected. Use /chatbot-intg to invoke.',
+  },
+  codex: {
+    skillDir: '.codex/skills/chatbot-intg',
+    commandDir: null,
+    commandFile: null,
+    instructionFile: '.codex/AGENTS.md',
+    postInstall: '  Codex: add to .codex/AGENTS.md:\n' +
+      '    "Read .codex/skills/chatbot-intg/SKILL.md for vendor integration workflow"',
+  },
+  gemini: {
+    skillDir: '.gemini/skills/chatbot-intg',
+    commandDir: null,
+    commandFile: null,
+    instructionFile: '.gemini/GEMINI.md',
+    postInstall: '  Gemini: add to .gemini/GEMINI.md:\n' +
+      '    "Read .gemini/skills/chatbot-intg/SKILL.md for vendor integration workflow"',
+  },
+};
+
+const COMMAND_TEMPLATE = `---
+description: AI Chatbot Integration — guides vendors through complete API integration (auth, chat, escalation, error handling, analysis, debugging)
+---
+
+# Chatbot Integration Workflow
+
+This command launches the chatbot-intg skill to guide a vendor through full AI Chatbot API integration.
+
+## Startup
+
+1. Read \`.claude/skills/chatbot-intg/SKILL.md\` and follow the phased workflow.
+2. Read \`docs/chatbot_integration_spec.md\` as the authoritative API reference.
+3. Reference \`.claude/skills/chatbot-intg/resources/integration-playbook.md\` for language-specific code templates.
+
+## Execution
+
+Begin with **Phase 0** — ask the vendor for their target language and integration scope, then proceed through each phase with user confirmation gates.
+`;
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+function ask(question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      console.log(`    copied: ${destPath}`);
+    }
+  }
+}
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const toolFlag = args.indexOf('--tool');
+  if (toolFlag !== -1 && args[toolFlag + 1]) {
+    return args[toolFlag + 1].split(',').map((s) => s.trim().toLowerCase());
+  }
+  return null;
+}
+
+async function selectTools() {
+  // Check --tool flag first
+  const fromArgs = parseArgs();
+  if (fromArgs) {
+    const valid = fromArgs.includes('all')
+      ? Object.keys(TARGETS)
+      : fromArgs.filter((t) => TARGETS[t]);
+    if (valid.length > 0) return valid;
+  }
+
+  // Interactive prompt
+  const answer = await ask(
+    '  Install for which tools? (comma-separated)\n' +
+      '  1) claude  2) codex  3) gemini  4) all\n' +
+      '  > '
+  );
+
+  if (answer.toLowerCase().includes('all') || answer.includes('4')) {
+    return Object.keys(TARGETS);
+  }
+
+  const mapping = { '1': 'claude', '2': 'codex', '3': 'gemini' };
+  return answer
+    .split(',')
+    .map((s) => {
+      const trimmed = s.trim().toLowerCase();
+      return mapping[trimmed] || trimmed;
+    })
+    .filter((s) => TARGETS[s]);
+}
+
+async function main() {
+  console.log('');
+  console.log('  AI Chatbot Integration Skill Installer');
+  console.log('  =======================================');
+  console.log('');
+
+  const choices = await selectTools();
+
+  if (choices.length === 0) {
+    console.log('  No valid targets selected. Exiting.\n');
+    rl.close();
+    process.exit(1);
+  }
+
+  const templateDir = path.join(__dirname, '..', 'templates');
+  const cwd = process.cwd();
+
+  for (const tool of choices) {
+    const target = TARGETS[tool];
+    const dest = path.join(cwd, target.skillDir);
+
+    console.log(`\n  [${tool}] Installing skill -> ${target.skillDir}/`);
+    copyDir(templateDir, dest);
+
+    // Create Claude Code command file
+    if (target.commandDir && target.commandFile) {
+      const cmdDir = path.join(cwd, target.commandDir);
+      const cmdFile = path.join(cmdDir, target.commandFile);
+      fs.mkdirSync(cmdDir, { recursive: true });
+      fs.writeFileSync(cmdFile, COMMAND_TEMPLATE);
+      console.log(`    copied: ${cmdFile}`);
+    }
+  }
+
+  console.log('\n  =======================================');
+  console.log('  Installation complete!\n');
+  console.log('  Next steps:\n');
+
+  for (const tool of choices) {
+    console.log(TARGETS[tool].postInstall);
+    console.log('');
+  }
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error('  Error:', err.message);
+  rl.close();
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@austinchen705/chatbot-intg-skill",
+  "version": "1.0.1",
+  "description": "AI Chatbot integration skill for Claude Code / Codex / Gemini — guides vendors through complete API integration",
+  "bin": {
+    "chatbot-intg-skill": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "keywords": [
+    "chatbot",
+    "integration",
+    "claude-code",
+    "codex",
+    "gemini",
+    "ai-skill"
+  ],
+  "license": "MIT"
+}

package/templates/SKILL.md

@@ -0,0 +1,452 @@
+---
+name: chatbot-intg
+description: AI Chatbot Integration Skill — guides vendors through complete Chatbot API integration including auth, chat, error handling, escalation, analysis, logging, and debugging. Supports Python / Java / C# / Node.js.
+---
+
+# AI Chatbot Integration Skill
+
+Guides third-party vendors through complete AI Chatbot system integration. Based on `resources/chatbot_integration_spec.pdf`, this skill generates phased tasks, code templates, error handling frameworks, and debugging guides per target language.
+
+## Use this skill when
+
+- A vendor needs to integrate with the AI Chatbot API (auth, chat, analysis)
+- Generating integration code for a specific language (Python / Java / C# / Node.js)
+- Designing error handling and resilience patterns based on the spec
+- Building debug/troubleshooting workflows and logging architecture
+
+## Do not use this skill when
+
+- Developing the Chatbot system internals (backend services, domain logic, database schema)
+- Only looking up a single API spec or error code (use the Consult Agent directly)
+- Building standalone applications unrelated to Chatbot API integration
+
+## Knowledge Source
+
+- **Integration Spec:** `resources/chatbot_integration_spec.pdf` (v0.7)
+- **Implementation Templates:** `resources/integration-playbook.md`
+
+---
+
+## Workflow Overview
+
+```
+Phase 0: Infrastructure      -> Language + Logging setup
+    | (user confirmation)
+Phase 1: Auth & Connectivity -> Auth module + Token management
+    | (user confirmation)
+Phase 2: Core Chat Flow      -> Session + Chat + Escalation
+    | (user confirmation)
+Phase 3: Error Handling      -> Unified error framework + Resilience
+    | (user confirmation)
+Phase 4: Advanced (optional) -> Chat Analysis + MCP Server guide
+    | (user confirmation)
+Phase 5: Acceptance          -> Test checklist + Debug handbook
+```
+
+**Each Phase requires user confirmation before proceeding to the next.**
+
+---
+
+## Phase 0: Infrastructure
+
+### Goal
+Confirm dev environment, tech stack, and establish the cross-cutting Logging approach.
+
+### Steps
+
+1. **Detect / Ask target language**
+   - Supported: Python / Java / C# / Node.js
+   - Confirm framework (e.g. Python: FastAPI/Django, Java: Spring Boot, C#: ASP.NET Core, Node.js: Express/NestJS)
+   - Confirm HTTP client preference (e.g. Python: httpx/requests, Java: OkHttp/RestTemplate)
+
+2. **Confirm integration scope**
+   - AI Chatbot (required): Auth + Chat + Escalation
+   - Chat Analysis (optional): Post-conversation quality analysis
+   - MCP Server (optional): Custom tool extension
+
+3. **Establish Logging approach**
+   - Ask the vendor about their existing logging setup and conventions
+   - Adapt all subsequent logging guidance to their architecture
+   - Ensure a **correlation ID** mechanism exists (or suggest adding one) to trace requests end-to-end
+   - All subsequent Phases will include logging points — these should follow the vendor's conventions
+
+4. **Suggest project structure**
+   - Generate recommended directory layout per language
+   - Generate base HTTP client wrapper
+
+### Output
+- Language & framework confirmed
+- Integration scope confirmed
+- Logging approach agreed
+- HTTP client base wrapper code
+- Task list for subsequent Phases
+
+### Gate
+User confirms language, scope, and infrastructure before entering Phase 1.
+
+---
+
+## Phase 1: Auth & Connectivity
+
+### Goal
+Implement JWT Token lifecycle management so all subsequent API calls carry a valid token.
+
+### Knowledge Source
+- Spec 2.1: Authentication
+- Error codes: `AUTH_001`~`AUTH_004`, `TENANT_001`, `TENANT_003`
+
+### Steps
+
+1. **Implement AuthService / AuthClient**
+   - Wrap `POST /api/v1/auth`
+   - Secure API Key storage (env vars / secret manager — never hardcode)
+   - Define Request/Response DTOs
+
+2. **Token caching & auto-refresh**
+   - In-memory cache with `expiresAt`
+   - Auto-detect expiry and refresh proactively (recommend 5 min before expiry)
+   - Thread-safe design (prevent concurrent refresh storms)
+
+3. **Auth error handling**
+   - `AUTH_004` (invalid API Key) -> do NOT retry, escalate immediately
+   - `TENANT_003` (tenant inactive) -> do NOT retry, notify admin
+   - Network errors -> retry (max 3, exponential backoff)
+
+4. **Logging**
+   - Log: auth success/failure, token refresh events, error codes
+   - NEVER log: raw API Key, full token (log only last 8 chars)
+
+### Output
+- AuthService complete code
+- Token management module
+- Auth-related error handling
+- Unit test suggestions
+
+### Gate
+User confirms Auth module can successfully obtain a token before entering Phase 2.
+
+---
+
+## Phase 2: Core Chat Flow
+
+### Goal
+Implement the full `dispatch -> send (loop) -> kickout` conversation lifecycle.
+
+### Knowledge Source
+- Spec 3.1: Flow Overview
+- Spec 3.2.1~3.2.5: All Chatbot & Chat APIs
+- Spec 6.4: EscalationReason enum
+- Error codes: `CHATBOT_001`~`CHATBOT_009`, `CHAT_001`~`CHAT_019`
+
+### Steps
+
+1. **Session lifecycle management**
+   - `POST /api/v1/chatbot/dispatch` — create session
+     - Handle idempotency (same sessionId won't consume extra quota)
+     - Handle `timeZone` param (IANA format)
+   - `GET /api/v1/chatbot/usage` — check quota before dispatch
+   - `POST /api/v1/chatbot/kickout` — graceful close
+   - `POST /api/v1/chatbot/killall` — bulk close (admin use)
+   - **Cleanup on failure**: if unexpected error occurs after dispatch, ensure kickout is called (similar to finally/dispose pattern)
+
+2. **Chat message send/receive**
+   - `POST /api/v1/chat/send`
+     - Required fields: `sessionId`, `message`, `userId`, `requestId`
+     - `requestId` for idempotency (recommend UUID)
+     - Client-side validation: message length <= 10,000 chars, sessionId 3~100 chars
+   - Response parsing: extract `content`, `escalationReason`, `shouldTransferHuman`
+
+3. **Escalation handling**
+   - Detect `shouldTransferHuman: true`
+   - Handle by `escalationReason` (11 types):
+
+   | Code | Name | Recommended Action |
+   |------|------|-------------------|
+   | 1 | ConsecutiveUnableToAnswer | Transfer to agent + attach conversation summary |
+   | 2 | SpecialKeyword | Route to designated department |
+   | 3 | EmotionalAnomaly | Priority transfer + flag as high-sensitivity |
+   | 4 | DuplicateQuestion | Transfer to agent + flag as repeated |
+   | 5 | TurnLimitExceeded | Transfer to agent + inform user |
+   | 6 | HateSpeech | Escalate to supervisor + log incident |
+   | 7 | PersonalDataVerification | Route to identity verification flow |
+   | 8 | VendorKeyword | Handle per vendor-defined logic |
+   | 9 | AllAiProvidersInactive | Transfer to agent + inform AI unavailable |
+   | 10 | ToolsError | Transfer to agent + log tool failure |
+   | 11 | AiDeterminedEscalation | Transfer to agent |
+
+   - Generate EscalationHandler interface (vendor implements their own transfer logic)
+
+4. **Chat history**
+   - `GET /api/v1/chat/history/{sessionId}` — retrieve conversation history
+   - Useful for attaching context when transferring to human agent
+
+5. **Logging**
+   - Log each send: correlation ID, session ID, duration, status
+   - Log escalation events (including reason)
+   - Log session lifecycle (create/close/error)
+
+### Output
+- SessionManager module
+- ChatService module
+- EscalationHandler interface + default implementation
+- All related DTOs
+- Client-side validation logic
+
+### Gate
+User confirms full chat flow works correctly before entering Phase 3.
+
+---
+
+## Phase 3: Error Handling & Resilience
+
+### Goal
+Build a unified error handling framework covering client validation, server business errors, and infrastructure errors.
+
+### Knowledge Source
+- Spec 2.2: Standard responses and error codes
+- Spec 6.3: Complete error code reference (8 categories)
+- Spec 2.2.3: Request timeout (60 seconds)
+
+### Steps
+
+1. **Unified API response parser**
+   - Standard structure: `{ isSuccess, data, error: { code, message, details, reference } }`
+   - Abstract `ApiResponse<T>` generic class
+   - All API calls go through this parser
+
+2. **Three-layer error classification**
+
+   **Layer 1: Client-side Validation (pre-call interception)**
+   - sessionId length 3~100 (CHAT_014/015)
+   - message non-empty + length <= 10,000 (CHAT_003/013)
+   - requestId GUID format (CHAT_011)
+   - userId length <= 100 (CHAT_016)
+   - Basic XSS/SQLi pattern detection (INPUT_005/006)
+
+   **Layer 2: Server Business Error (API-returned business errors)**
+   - Classify handling strategy by error code prefix:
+
+   | Prefix | Category | Strategy |
+   |--------|----------|----------|
+   | AUTH_ | Auth error | Token refresh + retry / escalate |
+   | TENANT_ | Tenant error | No retry, notify admin |
+   | CHATBOT_ | Session error | Re-dispatch / escalate |
+   | CHAT_ | Chat error | Handle per specific code |
+   | INPUT_ | Validation error | Fix input + retry / report to user |
+   | ANALYSIS_ | Analysis error | Retry later / ignore |
+   | AI_PROVIDER_ | AI error | Fallback to human transfer |
+   | SYSTEM_ | System error | Retry + escalate |
+
+   **Layer 3: Infrastructure Error (network / timeout / unexpected exceptions)**
+   - HTTP timeout (60s) -> retry
+   - Connection refused -> retry + circuit breaker
+   - 5xx -> retry (max 3)
+   - Unexpected exceptions -> log + fallback response
+
+3. **Retry & Resilience strategy**
+   - Retry: exponential backoff (1s -> 2s -> 4s), max 3 attempts
+   - Circuit breaker: 5 consecutive failures -> open for 30 seconds
+   - Timeout: 60 seconds per request
+   - Fallback: degraded response when all APIs are unavailable
+   - Generate language-specific implementation (Python: tenacity, Java: Resilience4j, C#: Polly, Node.js: cockatiel)
+
+4. **Custom exception hierarchy**
+   - `ChatbotApiException` (base)
+   - `AuthenticationException`
+   - `SessionException`
+   - `ChatException`
+   - `ValidationException`
+   - Each exception carries `errorCode`, `message`, `details`
+
+5. **Logging**
+   - Log every error: error code, HTTP status, retry count, correlation ID
+   - Log circuit breaker state changes
+   - Log retry events
+
+### Output
+- `ApiResponse<T>` unified parser module
+- Client-side validator
+- Error handler (three-layer classification logic)
+- Retry / circuit breaker configuration
+- Custom exception class hierarchy
+- Error code lookup table (code -> handling strategy)
+
+### Gate
+User confirms error handling framework is complete before entering Phase 4.
+
+---
+
+## Phase 4: Advanced Features (Optional)
+
+### Goal
+Implement Chat Analysis integration and MCP Server development guide based on vendor needs.
+
+### T9: Chat Analysis Integration
+
+#### Knowledge Source
+- Spec 4.1~4.2: Chat Analysis flow and APIs
+
+#### Steps
+
+1. **Submit analysis request**
+   - `POST /api/v1/analysis/create`
+   - Assemble `conversationMessages` (role: customer/cs/system)
+   - Assemble `categories` (id + description)
+   - Assemble `metadata` (userId, startTime, endTime, messageCount)
+   - Validation: at least 1 message, chronological order, timestamps cannot be in the future
+
+2. **Poll analysis result**
+   - `GET /api/v1/analysis/{sessionId}`
+   - Handle statuses: `pending` -> `processing` -> `completed` / `failed`
+   - Polling strategy: initial 5s -> increment to 30s -> max polling duration 10 min
+   - 202 (processing) -> continue polling
+   - 200 (completed) -> parse `summary` (overview, resolution, categories)
+
+3. **Error handling**
+   - `ANALYSIS_001` (not found) -> verify create was called
+   - `ANALYSIS_011` (in progress) -> wait for completion
+   - `ANALYSIS_009`/`ANALYSIS_010` -> fix input data
+
+### T10: MCP Server Development Guide
+
+#### Knowledge Source
+- Spec 5.1~5.4: Complete MCP Server specification
+
+#### Steps
+
+1. **MCP Server architecture overview**
+   - Streamable HTTP transport
+   - Stateless design principle
+   - JWT authentication
+
+2. **Tool definition conventions**
+   - snake_case naming, verb-first
+   - Description 50~200 chars, include use cases
+   - Structured return values (no plain text)
+   - Parameter Description is strongly recommended
+
+3. **Example code**
+   - Generate MCP Server skeleton per vendor language
+   - C# reference: spec section 6.1
+   - Other languages: generate via MCP SDK
+
+4. **Security configuration**
+   - JWT verification (HS256)
+   - Custom Headers support
+   - HTTPS enforcement
+
+### Gate
+User confirms advanced features are complete or skipped before entering Phase 5.
+
+---
+
+## Phase 5: Acceptance
+
+### Goal
+Generate integration test checklist and debug handbook so vendors can self-diagnose issues.
+
+### T11: Integration Test Checklist
+
+Generate test cases per API endpoint:
+
+```
+Auth
+  [ ] Valid API Key -> obtain token
+  [ ] Invalid API Key -> AUTH_004
+  [ ] Expired token -> auto-refresh succeeds
+
+Session
+  [ ] dispatch -> obtain sessionId
+  [ ] Duplicate dispatch (same sessionId) -> no extra quota consumed
+  [ ] Quota full -> CHATBOT_001
+  [ ] kickout -> graceful close
+  [ ] kickout non-existent session -> CHATBOT_002
+
+Chat
+  [ ] send message -> receive AI response
+  [ ] Empty message -> CHAT_003
+  [ ] Oversized message -> CHAT_013
+  [ ] send without dispatch -> CHAT_019
+  [ ] Escalation triggered -> shouldTransferHuman = true
+
+Resilience
+  [ ] API timeout -> auto-retry
+  [ ] Mid-request token expiry -> auto-refresh + retry
+  [ ] Consecutive failures -> circuit breaker activates
+
+Analysis (if enabled)
+  [ ] create -> 200 OK
+  [ ] Duplicate create -> 202 Accepted
+  [ ] get result (processing) -> continue polling
+  [ ] get result (completed) -> parse summary
+```
+
+### T12: Debug Handbook
+
+1. **Error code quick reference**
+   - Generated from spec 6.3: error code -> cause -> troubleshooting steps -> solution
+
+2. **Common issues FAQ**
+   - "Token keeps expiring" -> check clock sync / proactive refresh mechanism
+   - "dispatch always returns CHATBOT_001" -> check for un-closed sessions (kickout)
+   - "send returns CHAT_019" -> must dispatch first
+   - "AI keeps transferring to human" -> check escalationReason, may be GuardRail or emotion detection
+
+3. **Log analysis guide**
+   - How to trace a full request chain using correlation ID
+   - How to distinguish client-side vs server-side issues
+   - How to locate retry / timeout / circuit breaker events from logs
+
+4. **Self-service troubleshooting flowchart**
+   ```
+   Issue occurs
+     -> Check errorCode
+       -> Look up in error code quick reference
+       -> Follow troubleshooting steps
+       -> Check related logs (filter by correlationId)
+       -> Determine which layer (client / server / network)
+       -> Apply corresponding solution
+   ```
+
+### Output
+- Integration test checklist (exportable markdown)
+- Debug handbook (error code reference, FAQ, log analysis guide)
+- Self-service troubleshooting flowchart
+
+### Gate
+All phases complete.
+
+---
+
+## Completion Summary
+
+After all Phases are complete, output final summary:
+
+```
+Chatbot Integration Complete
+=============================
+Language:    [language]
+Scope:       [Chatbot / Analysis / MCP Server]
+Modules:
+  - AuthService          done
+  - SessionManager       done
+  - ChatService          done
+  - EscalationHandler    done
+  - ErrorHandler         done
+  - Retry/Resilience     done
+  - Logger               done
+  - Analysis (optional)  done / skipped
+  - MCP Server (optional)done / skipped
+
+Deliverables:
+  - Integration Test Checklist
+  - Debug Handbook
+  - Error Code Quick Reference
+```
+
+---
+
+## Resources
+
+- `resources/integration-playbook.md` — Language-specific implementation templates and code samples
+- `resources/chatbot_integration_spec.pdf` — API integration spec (v0.7)

package/templates/resources/integration-playbook.md

@@ -0,0 +1,625 @@
+# Integration Playbook
+
+Language-specific implementation templates for AI Chatbot API integration.
+
+> **Usage:** This playbook is referenced by `SKILL.md`. During each Phase, generate code based on the vendor's confirmed language and framework. The templates below provide structural patterns — adapt naming, style, and conventions to match the vendor's codebase.
+
+---
+
+## 1. HTTP Client Base Wrapper
+
+All API calls should go through a centralized HTTP client that handles:
+- Base URL configuration
+- Authorization header injection
+- Standard response parsing
+- Correlation ID propagation
+- Timeout enforcement (60s default)
+
+### Python (httpx)
+
+```python
+import httpx
+import uuid
+from dataclasses import dataclass
+from typing import TypeVar, Generic, Optional
+
+T = TypeVar("T")
+
+@dataclass
+class ApiError:
+    code: str
+    message: str
+    details: Optional[str] = None
+    reference: Optional[str] = None
+
+@dataclass
+class ApiResponse(Generic[T]):
+    is_success: bool
+    data: Optional[T] = None
+    error: Optional[ApiError] = None
+
+class ChatbotHttpClient:
+    def __init__(self, base_url: str, auth_service):
+        self._base_url = base_url.rstrip("/")
+        self._auth = auth_service
+        self._client = httpx.AsyncClient(timeout=60.0)
+
+    async def request(self, method: str, path: str, **kwargs) -> dict:
+        token = await self._auth.get_token()
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "X-Correlation-Id": str(uuid.uuid4()),
+            **kwargs.pop("headers", {}),
+        }
+        response = await self._client.request(
+            method, f"{self._base_url}{path}", headers=headers, **kwargs
+        )
+        response.raise_for_status()
+        return response.json()
+```
+
+### Java (OkHttp)
+
+```java
+public class ChatbotHttpClient {
+    private final String baseUrl;
+    private final AuthService authService;
+    private final OkHttpClient client;
+
+    public ChatbotHttpClient(String baseUrl, AuthService authService) {
+        this.baseUrl = baseUrl;
+        this.authService = authService;
+        this.client = new OkHttpClient.Builder()
+            .connectTimeout(60, TimeUnit.SECONDS)
+            .readTimeout(60, TimeUnit.SECONDS)
+            .build();
+    }
+
+    public <T> ApiResponse<T> request(String method, String path, Object body, Class<T> responseType) throws IOException {
+        String token = authService.getToken();
+        String correlationId = UUID.randomUUID().toString();
+
+        Request.Builder builder = new Request.Builder()
+            .url(baseUrl + path)
+            .header("Authorization", "Bearer " + token)
+            .header("X-Correlation-Id", correlationId);
+
+        // ... build request body, execute, parse response
+    }
+}
+```
+
+### C# (HttpClient)
+
+```csharp
+public class ChatbotHttpClient
+{
+    private readonly HttpClient _httpClient;
+    private readonly IAuthService _authService;
+
+    public ChatbotHttpClient(HttpClient httpClient, IAuthService authService)
+    {
+        _httpClient = httpClient;
+        _authService = authService;
+        _httpClient.Timeout = TimeSpan.FromSeconds(60);
+    }
+
+    public async Task<ApiResponse<T>> RequestAsync<T>(HttpMethod method, string path, object? body = null)
+    {
+        var token = await _authService.GetTokenAsync();
+        var correlationId = Guid.NewGuid().ToString();
+
+        var request = new HttpRequestMessage(method, path);
+        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
+        request.Headers.Add("X-Correlation-Id", correlationId);
+
+        if (body != null)
+            request.Content = JsonContent.Create(body);
+
+        var response = await _httpClient.SendAsync(request);
+        var content = await response.Content.ReadFromJsonAsync<ApiResponse<T>>();
+        return content!;
+    }
+}
+```
+
+### Node.js (axios)
+
+```typescript
+import axios, { AxiosInstance } from 'axios';
+import { v4 as uuidv4 } from 'uuid';
+
+interface ApiResponse<T> {
+  isSuccess: boolean;
+  data: T | null;
+  error: { code: string; message: string; details?: string; reference?: string } | null;
+}
+
+class ChatbotHttpClient {
+  private client: AxiosInstance;
+  private authService: AuthService;
+
+  constructor(baseUrl: string, authService: AuthService) {
+    this.authService = authService;
+    this.client = axios.create({
+      baseURL: baseUrl,
+      timeout: 60000,
+    });
+  }
+
+  async request<T>(method: string, path: string, data?: any): Promise<ApiResponse<T>> {
+    const token = await this.authService.getToken();
+    const response = await this.client.request<ApiResponse<T>>({
+      method,
+      url: path,
+      data,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'X-Correlation-Id': uuidv4(),
+      },
+    });
+    return response.data;
+  }
+}
+```
+
+---
+
+## 2. AuthService — Token Lifecycle
+
+Key behaviors:
+- Obtain token via `POST /api/v1/auth`
+- Cache token in memory with `expiresAt`
+- Auto-refresh 5 minutes before expiry
+- Thread-safe (prevent concurrent refresh)
+
+### Python
+
+```python
+import asyncio
+from datetime import datetime, timezone, timedelta
+
+class AuthService:
+    def __init__(self, base_url: str, api_key: str):
+        self._base_url = base_url
+        self._api_key = api_key
+        self._token: Optional[str] = None
+        self._expires_at: Optional[datetime] = None
+        self._lock = asyncio.Lock()
+
+    async def get_token(self) -> str:
+        if self._is_token_valid():
+            return self._token
+
+        async with self._lock:
+            # Double-check after acquiring lock
+            if self._is_token_valid():
+                return self._token
+            await self._refresh_token()
+            return self._token
+
+    def _is_token_valid(self) -> bool:
+        if not self._token or not self._expires_at:
+            return False
+        # Refresh 5 minutes before expiry
+        return datetime.now(timezone.utc) < self._expires_at - timedelta(minutes=5)
+
+    async def _refresh_token(self):
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self._base_url}/api/v1/auth",
+                json={"apiKey": self._api_key},
+            )
+            response.raise_for_status()
+            data = response.json()["data"]
+            self._token = data["token"]
+            self._expires_at = datetime.fromisoformat(data["expiresAt"])
+```
+
+### C#
+
+```csharp
+public class AuthService : IAuthService
+{
+    private readonly string _baseUrl;
+    private readonly string _apiKey;
+    private readonly HttpClient _httpClient;
+    private readonly SemaphoreSlim _lock = new(1, 1);
+    private string? _token;
+    private DateTimeOffset? _expiresAt;
+
+    public async Task<string> GetTokenAsync()
+    {
+        if (IsTokenValid()) return _token!;
+
+        await _lock.WaitAsync();
+        try
+        {
+            if (IsTokenValid()) return _token!;
+            await RefreshTokenAsync();
+            return _token!;
+        }
+        finally { _lock.Release(); }
+    }
+
+    private bool IsTokenValid()
+        => _token != null && _expiresAt > DateTimeOffset.UtcNow.AddMinutes(5);
+
+    private async Task RefreshTokenAsync()
+    {
+        var response = await _httpClient.PostAsJsonAsync(
+            $"{_baseUrl}/api/v1/auth", new { apiKey = _apiKey });
+        response.EnsureSuccessStatusCode();
+        var result = await response.Content.ReadFromJsonAsync<ApiResponse<AuthData>>();
+        _token = result!.Data!.Token;
+        _expiresAt = result.Data.ExpiresAt;
+    }
+}
+```
+
+---
+
+## 3. SessionManager
+
+Key behaviors:
+- `dispatch` -> create session (idempotent)
+- Check quota via `usage` before dispatching
+- `kickout` -> graceful close
+- Cleanup guarantee (dispose/finally pattern)
+
+### Pattern (language-agnostic pseudocode)
+
+```
+class SessionManager:
+    async dispatch(sessionId, timeZone?):
+        // 1. Check quota
+        usage = await client.GET("/api/v1/chatbot/usage")
+        if usage.isLimitReached:
+            throw QuotaExceededException
+
+        // 2. Dispatch
+        result = await client.POST("/api/v1/chatbot/dispatch", {sessionId, timeZone})
+        log("Session dispatched", {sessionId, remainingQuota: result.remainingQuota})
+        return result
+
+    async close(sessionId, reason?):
+        result = await client.POST("/api/v1/chatbot/kickout", {sessionId, reason})
+        log("Session closed", {sessionId})
+        return result
+
+    // Dispose pattern — ensure session is closed on error
+    async withSession(sessionId, callback):
+        try:
+            session = await dispatch(sessionId)
+            return await callback(session)
+        finally:
+            await close(sessionId, "auto-cleanup")
+```
+
+---
+
+## 4. ChatService
+
+Key behaviors:
+- Send message and parse response
+- Detect escalation signals
+- Client-side validation before sending
+
+### Pattern
+
+```
+class ChatService:
+    async send(sessionId, message, userId, requestId?):
+        // 1. Client-side validation
+        validate(sessionId, message, userId)
+
+        // 2. Send
+        requestId = requestId ?? generateUUID()
+        result = await client.POST("/api/v1/chat/send", {
+            sessionId, message, userId, requestId
+        })
+
+        // 3. Check escalation
+        if result.shouldTransferHuman:
+            await escalationHandler.handle(sessionId, result.escalationReason, result.content)
+
+        return result
+
+    validate(sessionId, message, userId):
+        if len(sessionId) < 3 or len(sessionId) > 100:
+            throw ValidationException("CHAT_014/015", "sessionId length must be 3-100")
+        if not message or len(message) > 10000:
+            throw ValidationException("CHAT_003/013", "message required, max 10000 chars")
+        if len(userId) > 100:
+            throw ValidationException("CHAT_016", "userId max 100 chars")
+```
+
+---
+
+## 5. EscalationHandler
+
+Interface pattern — vendor implements their own transfer logic.
+
+### C# Example
+
+```csharp
+public interface IEscalationHandler
+{
+    Task HandleAsync(string sessionId, int escalationReason, string aiMessage);
+}
+
+public class DefaultEscalationHandler : IEscalationHandler
+{
+    public async Task HandleAsync(string sessionId, int escalationReason, string aiMessage)
+    {
+        // Fetch conversation history for context
+        var history = await _chatClient.GetHistoryAsync(sessionId);
+
+        switch (escalationReason)
+        {
+            case 3: // EmotionalAnomaly
+                await TransferWithPriority(sessionId, history, priority: "high");
+                break;
+            case 6: // HateSpeech
+                await EscalateToSupervisor(sessionId, history);
+                break;
+            case 7: // PersonalDataVerification
+                await RouteToVerificationFlow(sessionId, history);
+                break;
+            default:
+                await TransferToAgent(sessionId, history);
+                break;
+        }
+    }
+}
+```
+
+---
+
+## 6. Error Handling Framework
+
+### ApiResponse<T> — Unified Response Parser
+
+```
+class ApiResponse<T>:
+    isSuccess: bool
+    data: T?
+    error: ApiError?
+
+class ApiError:
+    code: string       // e.g. "AUTH_004"
+    message: string
+    details: string?
+    reference: string?
+```
+
+### Exception Hierarchy
+
+```
+ChatbotApiException (base)
+  |-- AuthenticationException    (AUTH_*)
+  |-- TenantException           (TENANT_*)
+  |-- SessionException          (CHATBOT_*)
+  |-- ChatException             (CHAT_*)
+  |-- ValidationException       (INPUT_*, VALIDATION_*)
+  |-- AnalysisException         (ANALYSIS_*)
+  |-- AiProviderException       (AI_PROVIDER_*)
+  |-- SystemException           (SYSTEM_*)
+```
+
+### Error Code -> Strategy Mapping
+
+```
+ERROR_CODE_STRATEGIES = {
+    # Auth — no retry (except network), escalate
+    "AUTH_001": {"retry": false, "action": "escalate"},
+    "AUTH_002": {"retry": false, "action": "re-authenticate"},
+    "AUTH_003": {"retry": true,  "action": "retry_then_escalate"},
+    "AUTH_004": {"retry": false, "action": "escalate_invalid_key"},
+
+    # Tenant — no retry, admin notification
+    "TENANT_001": {"retry": false, "action": "notify_admin"},
+    "TENANT_003": {"retry": false, "action": "notify_admin"},
+
+    # Session — conditional retry
+    "CHATBOT_001": {"retry": false, "action": "check_quota_then_cleanup"},
+    "CHATBOT_002": {"retry": false, "action": "re_dispatch"},
+    "CHATBOT_003": {"retry": false, "action": "re_dispatch"},
+
+    # Chat — per-code handling
+    "CHAT_003":  {"retry": false, "action": "fix_input"},
+    "CHAT_013":  {"retry": false, "action": "truncate_message"},
+    "CHAT_019":  {"retry": false, "action": "dispatch_first"},
+
+    # Input — fix and retry
+    "INPUT_005": {"retry": false, "action": "sanitize_input"},
+    "INPUT_006": {"retry": false, "action": "sanitize_input"},
+
+    # System — retry with backoff
+    "SYSTEM_001": {"retry": true, "action": "retry_then_escalate"},
+}
+```
+
+---
+
+## 7. Retry & Resilience
+
+### Python (tenacity)
+
+```python
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=1, max=4),
+    retry=retry_if_exception_type((httpx.TimeoutException, httpx.NetworkError)),
+)
+async def call_with_retry(func, *args, **kwargs):
+    return await func(*args, **kwargs)
+```
+
+### C# (Polly)
+
+```csharp
+var retryPolicy = Policy
+    .Handle<HttpRequestException>()
+    .Or<TaskCanceledException>()
+    .WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt - 1)));
+
+var circuitBreaker = Policy
+    .Handle<HttpRequestException>()
+    .CircuitBreakerAsync(5, TimeSpan.FromSeconds(30));
+
+var resilience = Policy.WrapAsync(retryPolicy, circuitBreaker);
+```
+
+### Java (Resilience4j)
+
+```java
+RetryConfig retryConfig = RetryConfig.custom()
+    .maxAttempts(3)
+    .waitDuration(Duration.ofSeconds(1))
+    .retryExceptions(IOException.class, TimeoutException.class)
+    .build();
+
+CircuitBreakerConfig cbConfig = CircuitBreakerConfig.custom()
+    .failureRateThreshold(50)
+    .waitDurationInOpenState(Duration.ofSeconds(30))
+    .slidingWindowSize(5)
+    .build();
+```
+
+### Node.js (cockatiel)
+
+```typescript
+import { retry, handleAll, ExponentialBackoff, circuitBreaker, SamplingBreaker, wrap } from 'cockatiel';
+
+const retryPolicy = retry(handleAll, { maxAttempts: 3, backoff: new ExponentialBackoff() });
+const breaker = circuitBreaker(handleAll, {
+  halfOpenAfter: 30 * 1000,
+  breaker: new SamplingBreaker({ threshold: 0.5, duration: 30 * 1000, minimumRps: 1 }),
+});
+const resilience = wrap(retryPolicy, breaker);
+```
+
+---
+
+## 8. Chat Analysis (Optional)
+
+### Polling Pattern
+
+```
+class AnalysisService:
+    async createAnalysis(sessionId, messages, categories?, metadata?):
+        return await client.POST("/api/v1/analysis/create", {
+            sessionId, conversationMessages: messages, categories, metadata
+        })
+
+    async waitForResult(sessionId, maxWaitSeconds=600):
+        interval = 5  // start at 5 seconds
+        elapsed = 0
+
+        while elapsed < maxWaitSeconds:
+            result = await client.GET(f"/api/v1/analysis/{sessionId}")
+
+            if result.status == "completed":
+                return result.summary
+            if result.status == "failed":
+                throw AnalysisFailedException(result.message)
+
+            await sleep(interval)
+            elapsed += interval
+            interval = min(interval * 1.5, 30)  // cap at 30 seconds
+
+        throw AnalysisTimeoutException(sessionId)
+```
+
+---
+
+## 9. Suggested Project Structures
+
+### Python
+```
+chatbot_integration/
+  __init__.py
+  client.py          # ChatbotHttpClient
+  auth.py            # AuthService
+  session.py         # SessionManager
+  chat.py            # ChatService
+  escalation.py      # EscalationHandler
+  analysis.py        # AnalysisService (optional)
+  errors.py          # Exception hierarchy + error strategies
+  models.py          # DTOs / dataclasses
+  config.py          # Configuration
+tests/
+  test_auth.py
+  test_session.py
+  test_chat.py
+```
+
+### Java (Spring Boot)
+```
+src/main/java/com/vendor/chatbot/
+  client/
+    ChatbotHttpClient.java
+  service/
+    AuthService.java
+    SessionManager.java
+    ChatService.java
+    EscalationHandler.java
+    AnalysisService.java
+  model/
+    ApiResponse.java
+    AuthData.java
+    ChatResponse.java
+  exception/
+    ChatbotApiException.java
+    (subclasses)
+  config/
+    ChatbotConfig.java
+    ResilienceConfig.java
+```
+
+### C# (ASP.NET Core)
+```
+ChatbotIntegration/
+  Clients/
+    ChatbotHttpClient.cs
+  Services/
+    AuthService.cs
+    SessionManager.cs
+    ChatService.cs
+    IEscalationHandler.cs
+    AnalysisService.cs
+  Models/
+    ApiResponse.cs
+    DTOs/
+  Exceptions/
+    ChatbotApiException.cs
+    (subclasses)
+  Configuration/
+    ChatbotOptions.cs
+  DependencyInjection.cs
+```
+
+### Node.js (TypeScript)
+```
+src/
+  client/
+    chatbot-http-client.ts
+  services/
+    auth.service.ts
+    session.service.ts
+    chat.service.ts
+    escalation.handler.ts
+    analysis.service.ts
+  models/
+    api-response.ts
+    dtos.ts
+  errors/
+    chatbot-api.error.ts
+    (subclasses)
+  config/
+    chatbot.config.ts
+  index.ts
+```