@optima-chat/dev-skills 0.7.26 → 0.7.27

package/.claude/settings.local.json

@@ -0,0 +1,51 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:code.claude.com)",
+      "WebFetch(domain:platform.claude.com)",
+      "WebFetch(domain:github.com)",
+      "Bash(gh repo view:*)",
+      "Bash(gh repo clone:*)",
+      "Bash(gh repo list:*)",
+      "Read(//private/tmp/optima-docs/**)",
+      "Read(//tmp/optima-docs/**)",
+      "Bash(git init:*)",
+      "Bash(gh repo create:*)",
+      "Read(//private/tmp/optima-workspace/**)",
+      "Read(//tmp/optima-workspace/**)",
+      "Read(//tmp/optima-workspace/.claude/commands/**)",
+      "Bash(git add:*)",
+      "Bash(git push:*)",
+      "Bash(find:*)",
+      "Bash(git commit:*)",
+      "Bash(aws logs get-log-events:*)",
+      "Bash(npm install:*)",
+      "Bash(optima-dev-skills:*)",
+      "Bash(optima-generate-test-token:*)",
+      "Bash(optima-query-db:*)",
+      "Bash(gh variable set:*)",
+      "Bash(npm publish:*)",
+      "Bash(python3:*)",
+      "Bash(gh api:*)",
+      "Bash(curl -s http://auth.optima.chat/openapi.json)",
+      "Bash(curl -s https://auth.optima.chat/openapi.json)",
+      "Bash(cat:*)",
+      "Bash(node /Users/verypro/optima-dev-skills/scripts/install.js:*)",
+      "Bash(aws logs tail:*)",
+      "Bash(grep:*)",
+      "Bash(npm view:*)",
+      "Bash(npm version:*)",
+      "Bash(git checkout:*)",
+      "Bash(git pull:*)",
+      "Bash(node scripts/install.js:*)",
+      "Bash(gh issue:*)",
+      "Bash(npm run:*)",
+      "Bash(gh pr:*)",
+      "Bash(node:*)",
+      "Bash(echo \"exit: $?\")"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.codex/skills/generate-test-token/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: "generate-test-token"
+description: "Use when the user needs a test merchant account, an access token for API testing, or a temporary account for CI, Stage, or Prod verification."
+---
+
+# Generate Test Access Tokens
+
+Use this skill when the user needs a usable Optima merchant token for API testing.
+
+## Preferred Command
+
+```bash
+optima-generate-test-token [options]
+```
+
+## Examples
+
+```bash
+optima-generate-test-token
+optima-generate-test-token --env stage
+optima-generate-test-token --business-name "Demo Shop" --env prod
+```
+
+## Guidance
+
+- Default to `ci`.
+- The command handles merchant registration, OAuth token creation, and merchant profile setup.
+- The command writes the token to a temporary file; report that path back to the user.
+- For `prod`, remind the user that the created account will exist in the production system.
+
+## Follow-up
+
+Use the generated token with `commerce` CLI commands or `curl` requests.

package/.codex/skills/grant-credits/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: "grant-credits"
+description: "Use when the user wants to add bonus or referral credits to an Optima user without changing their subscription."
+---
+
+# Grant Credits
+
+Use this skill when the user asks to add credits directly.
+
+## Preferred Command
+
+```bash
+optima-grant-credits <email> --amount <n> [options]
+```
+
+## Examples
+
+```bash
+optima-grant-credits user@example.com --amount 100
+optima-grant-credits user@example.com --amount 500 --env prod
+optima-grant-credits user@example.com --amount 300 --type referral --env prod
+```
+
+## Guidance
+
+- Default to `stage`.
+- Confirm the email and amount before using `prod`.
+- This operation appends credits and does not replace the user's subscription.

package/.codex/skills/grant-subscription/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "grant-subscription"
+description: "Use when the user wants to grant or change a subscription plan such as trial, starter, pro, or enterprise for an Optima user."
+---
+
+# Grant Subscriptions
+
+Use this skill when the user asks to open or change a subscription plan.
+
+## Preferred Command
+
+```bash
+optima-grant-subscription <email> [options]
+```
+
+## Examples
+
+```bash
+optima-grant-subscription user@example.com
+optima-grant-subscription user@example.com --plan starter --months 3
+optima-grant-subscription user@example.com --plan enterprise --env prod
+```
+
+## Guidance
+
+- Default to `stage`.
+- Confirm the user email before running on `prod`.
+- This operation replaces existing subscription state and resets credits according to the selected plan.
+- Use `optima-query-db` afterward if the user asks for verification.

package/.codex/skills/logs/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: "logs"
+description: "Use when the user asks to inspect service logs, debug runtime failures, or compare CI, Stage, and Prod logs for Optima services."
+---
+
+# Inspect Service Logs
+
+Use this skill when the user needs service logs for debugging or operational checks.
+
+## Preferred Flow
+
+Use the local shell and follow the environment-specific workflow:
+
+- `ci`: SSH to the shared CI host and read Docker Compose logs
+- `stage`: read AWS CloudWatch logs from `/ecs/<service>-stage`
+- `prod`: read AWS CloudWatch logs from `/ecs/<service>-prod` with `--region ap-southeast-1`
+
+## Common Services
+
+- `commerce-backend`
+- `user-auth`
+- `agentic-chat`
+- `bi-backend`
+- `session-gateway`
+- `optima-scout`
+- `billing`
+- `browser-backend`
+- `optima-generation`
+
+## Guidance
+
+- Default to `ci` unless the user clearly requests `stage` or `prod`.
+- For `prod`, keep the query narrow and use the exact service the user asked for.
+- When investigating an error, read enough context around the failure instead of only grepping a single line.
+
+## Related Skills
+
+- `query-db` for data verification after log analysis
+- `show-env` for configuration-related failures
+- `restart-ecs` for controlled service restarts

package/.codex/skills/query-db/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: "query-db"
+description: "Use when the user asks to query Optima databases, inspect rows, validate data, or run SQL in CI, Stage, or Prod."
+---
+
+# Query Databases
+
+Use this skill for SQL queries against Optima service databases.
+
+## Preferred Command
+
+Always prefer:
+
+```bash
+optima-query-db <service> "<sql>" [environment]
+```
+
+## Services
+
+- `commerce-backend`
+- `user-auth`
+- `agentic-chat`
+- `bi-backend`
+- `session-gateway`
+- `optima-logistics`
+- `billing`
+- `browser-backend`
+- `optima-generation`
+
+## Guidance
+
+- Default to `ci` when the user does not specify an environment.
+- For `prod`, restrict usage to focused `SELECT` queries.
+- Prefer explicit columns and `LIMIT` over `SELECT *`.
+- Use the CLI instead of rebuilding Infisical and SSH tunnel steps manually.
+
+## Fallback
+
+If the CLI is unavailable, fall back to the documented manual SSH/Infisical workflow from the repository docs or Claude skill content.

package/.codex/skills/read-code/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: "read-code"
+description: "Use when the user wants to inspect code, repository structure, implementation details, or compare repositories under the Optima-Chat GitHub organization."
+---
+
+# Read Optima Repositories
+
+Use this skill when the user asks to inspect code from another Optima repository.
+
+## Preferred Tools
+
+Use GitHub CLI against `Optima-Chat/<repo>`:
+
+- `gh repo view`
+- `gh api repos/Optima-Chat/<repo>/contents/...`
+- `gh search code ... --repo Optima-Chat/<repo>`
+
+## Common Repositories
+
+- `commerce-backend`
+- `user-auth`
+- `mcp-host`
+- `agentic-chat`
+- `commerce-mcp`
+- `shopify-mcp`
+- `google-ads-mcp`
+- `optima-store`
+- `commerce-cli`
+- `optima-terraform`
+
+## Guidance
+
+- Read `README.md` or `CLAUDE.md` first when present.
+- For large files, use the GitHub `download_url` or raw content endpoint.
+- Prefer targeted code search before opening many files.

package/.codex/skills/restart-ecs/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: "restart-ecs"
+description: "Use when the user asks to restart or redeploy an ECS service in Stage or Prod."
+---
+
+# Restart ECS Services
+
+Use this skill when the user needs an ECS service restart.
+
+## Preferred Workflow
+
+Use AWS ECS `update-service --force-new-deployment` against the correct cluster:
+
+- `optima-stage-cluster`
+- `optima-prod-cluster`
+
+## Guidance
+
+- Default to `stage`.
+- Confirm before restarting `prod`.
+- Treat this as an operational change, not a debugging shortcut; read logs first when possible.
+- After triggering the restart, check service deployment status if the user asks for confirmation.

package/.codex/skills/show-env/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: "show-env"
+description: "Use when the user asks to inspect environment variables, service configuration, or Infisical-backed settings for Stage or Prod."
+---
+
+# Inspect Environment Configuration
+
+Use this skill to inspect current shell environment variables or service configuration stored in Infisical.
+
+## Preferred Command
+
+```bash
+optima-show-env <service> <stage|prod> [options]
+```
+
+## Common Options
+
+```bash
+optima-show-env commerce-backend stage --filter DATABASE
+optima-show-env user-auth prod --keys-only
+```
+
+## Guidance
+
+- For local shell variables, simple shell commands like `env` or `echo $VAR` are enough.
+- For service configuration, prefer `optima-show-env` over raw Infisical API calls.
+- If the user only needs key names, use `--keys-only` to avoid exposing values unnecessarily.

package/.codex/skills/use-commerce-cli/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "use-commerce-cli"
+description: "Use when the user wants to manage Optima commerce resources such as products, orders, inventory, collections, storefront content, or localization through the commerce CLI."
+---
+
+# Use Commerce CLI
+
+Use this skill when the user wants to manage store resources through the `commerce` CLI.
+
+## Requirements
+
+Set both:
+
+- `OPTIMA_TOKEN`
+- `OPTIMA_ENV`
+
+## Example
+
+```bash
+OPTIMA_TOKEN=$(cat /tmp/optima-test-token-xxx.txt) \
+OPTIMA_ENV=ci \
+commerce product list
+```
+
+## Guidance
+
+- If the user does not already have a token, use the `generate-test-token` skill first.
+- Match `OPTIMA_ENV` to the token environment.
+- Prefer explicit commands over broad destructive bulk actions.

package/AGENTS.md

@@ -0,0 +1,58 @@
+# Optima Dev Skills For Codex
+
+This repository provides shared development skills and CLI helpers for Optima engineers across `ci`, `stage`, and `prod`.
+
+## Primary Entry Points
+
+Prefer the installed CLI tools over reimplementing long shell workflows:
+
+- `optima-query-db <service> "<sql>" [environment]`
+- `optima-show-env <service> <stage|prod> [options]`
+- `optima-generate-test-token [options]`
+- `optima-grant-subscription <email> [options]`
+- `optima-grant-credits <email> --amount <n> [options]`
+
+For code-reading tasks across Optima repositories, use `gh` commands against `Optima-Chat/<repo>`.
+
+## Installed Codex Skills
+
+After `npm install -g @optima-chat/dev-skills`, this package installs skills under `~/.codex/skills/optima-dev/`:
+
+- `logs`
+- `query-db`
+- `show-env`
+- `generate-test-token`
+- `read-code`
+- `grant-subscription`
+- `grant-credits`
+- `restart-ecs`
+- `use-commerce-cli`
+
+## Tooling Assumptions
+
+Most operational commands depend on local access to:
+
+- `gh`
+- `curl`
+- `ssh` / `sshpass`
+- `aws`
+- `psql`
+
+Some flows also require:
+
+- GitHub Variables on `Optima-Chat/optima-dev-skills`
+- Infisical access
+- `~/.ssh/optima-ec2-key` for Stage/Prod database access
+
+## Safety Rules
+
+- Default to `ci` or `stage` when possible.
+- Treat `prod` as read-only unless the user explicitly asks for a write action.
+- For `prod`, prefer limited queries and targeted operational commands.
+- Do not expose secrets unless the user explicitly asks to inspect them.
+
+## Platform Notes
+
+- Claude Code uses `.claude/commands` and `.claude/skills`.
+- Codex uses the installed skills plus this repository guidance.
+- The shared source of truth for actual behavior is the CLI/helper implementation under `bin/helpers/`.

package/README.md

@@ -10,9 +10,18 @@
 npm install -g @optima-chat/dev-skills@latest
 ```
 
-安装后会自动将 skills 复制到 `~/.claude/` 目录。
+安装后会自动将 Claude 资源复制到 `~/.claude/`，并将 Codex skills 复制到 `~/.codex/skills/optima-dev/`。
 
-安装后，`/logs` 命令和 `logs` skill 会自动可用。
+安装后，`/logs` 命令和 `logs` skill 会在 Claude Code 中可用；Codex 会同时获得对应的本地 skills。
+
+## 🤖 Codex 支持
+
+本仓库现在同时支持 **Claude Code** 和 **Codex**：
+
+- **Claude Code** 使用 `.claude/commands` 和 `.claude/skills`
+- **Codex** 使用安装到 `~/.codex/skills/optima-dev/` 的 skills，以及仓库内的 `AGENTS.md`
+
+如果你设置了 `CODEX_HOME`，安装器会改为写入 `$CODEX_HOME/skills/optima-dev/`。
 
 ## 🎯 核心理念
 
@@ -102,6 +111,7 @@ Claude:
 - ✅ 可在任何终端直接使用
 - ✅ 自动注册账户、获取 token、设置 merchant profile（generate-test-token）
 - ✅ Claude Code 的命令内部也使用这些工具
+- ✅ Codex skills 也优先调用这些工具
 
 ## 🏗️ 项目结构