AGENTS.md — working rules for this repository

social-flow is a Claude Code plugin: 29 skills, 5 reviewer agents, and one bundled MCP server. README.md is the source of truth for structure and the tool list; CLAUDE.md holds the owner's dated production directives (the later date wins), the branch flow, the commit rules and the Korean prose rules. Read CLAUDE.md before you write anything — no checker runs on docs, comments or tool descriptions, so the writer holds the style line with the D8 scan quoted there.

GitHub authentication — owner directive, 2026-10-16

For this ttalkkaklab/social-flow repository, prefer the environment variable TTALKKAKLAB_GITHUB_TOKEN over generic GITHUB_TOKEN or GH_TOKEN. Before push, PR creation or merge, use it for both GH_TOKEN and GITHUB_TOKEN in the command's environment. This also lets Git's configured gh auth git-credential helper use the correct account. Verify the account with gh api user --jq .login and the repository's push permission; do not assume the generic token belongs to ttalkkaklab. Never print a token, put it in a remote URL, persist it in a file or change global authentication for this task. If the dedicated variable is absent or lacks access, report that specific blocker without revealing its value.

Tool lanes — one lane each

These are the lanes the skills are allowed to name. A skill's allowed-tools may list the plugin's own server and nothing else; a host CLI's native media tools are not MCP tools and never appear there.

ego lite has no fallback. It is macOS-only. Where it is missing, the skill says so and stops; it does not reach for a second browser. Two of these lanes exist because a fallback lane rotted in place — six chrome-devtools tools and eighteen claude-in-chrome tools sat in allowed-tools for versions after the servers were gone from every machine that runs this plugin.

Local GenAI connection — owner directive, 2026-11-07

For /Volumes/data/story/insight, astra-genai-native / qwen-image-fast means the local GenAI gateway at http://127.0.0.1:18081, backed by MLX Serve (qwen-image-2.1-turbo). Before generation, verify the image endpoint and credential are available to the MCP server process, then call astra_genai_catalog kind:image and confirm that alias and protocol. A shell's environment is not evidence that an already-running MCP server inherited it. Forward ASTRA_GENAI_IMAGE_URL and ASTRA_GENAI_IMAGE_API_KEY; speech uses the corresponding SPEECH variables. Keep the existing remote video route separate. Never print or persist secret values. For a Codex STDIO connection, include the six ASTRA_GENAI_* names (base URL/key, image URL/key and speech URL/key) in mcp_servers.social-flow.env_vars; write variable names only. Verify a fresh connection with that whitelist. Updating config does not change the environment of a server that is already running.

If a call unexpectedly reaches https://genai.astravision.co.kr, returns an empty model list or says Model capability is disabled, compare its receipt's baseUrl with the last successful receipt. Restore the same local route before proposing a different model or asking the user to select one. Check uncertain requests before retrying; do not discard their receipts. A fresh invocation of this plugin's own MCP server may inherit the correct shell environment when the session's connection is stale. Verify recovery with an actual requested image and its local receipt.

Images containing text

For every new image generation or edit that must display or preserve readable text, use GPT Image 2 (gpt-image-2). This owner directive (2026-10-18) overrides saved image defaults and the host-first lane above. Verify the host model or use the plugin GPT Image adapter; never assume host-managed identifies GPT Image 2. See CLAUDE.md and image routing for scoped selection, unavailable-model handling and text inspection.

Skill frontmatter

• description is the routing surface. Codex truncates it to about 76 characters (measured on codex-cli 0.149.1), so the first clause has to say what the skill does and where it stops. Trigger phrases come after that clause.
• Keep it under 1,024 characters, and keep <angle> placeholders out of it — write data/[channel]/episodes/[topic]/ instead.
• Where two skills could catch the same request, each description says the boundary in its own words. storyboard plans and stops for approval · produce builds an approved episode · autoproduce runs both unattended.
• argument-hint stays. Codex ignores the field and loads the skill anyway (measured: every skill present in codex debug prompt-input), and Claude Code uses it.
• allowed-tools names each of this server's tools twice: mcp__social-flow__<tool> (a project .mcp.json, Codex) and mcp__plugin_social-flow_social-flow__<tool> (a Claude Code marketplace install). Claude Code permission rules match a plugin server only in the plugin form, so the bare name alone pre-approves nothing there. skill-lint holds the pair.
• Never put disable-model-invocation: true on a grow-* skill — besides hiding it from the model, it stops a scheduled task or /loop from running the skill.

Before you say it works

cd server && npm run check           # build + contract tests
cd .. && node skills/platform-guide/references/skill-lint.js

skill-lint.js checks the frontmatter rules above, the tool lanes, and that no skill points at a reference file that isn't there. Both run in CI (.github/workflows/check.yml) — a green local run is what a PR needs.

New tests follow CLAUDE.md's "Tests — few, one file per module" section: add cases to the tested module's existing file, and only for behavior the change adds or alters. server/test/test-layout.test.mjs rejects a test file named after no module.

Anything under data/ is a local artifact and never gets committed. server/dist/ is a build artifact that must be committed, because marketplace installs never run npm install.

워크트리 경로 — 사용자 지침, 2026-10-10

• 새 워크트리는 이 저장소의 기본 체크아웃 루트 아래 .worktree/<이름>/에 만든다.
• 연결된 워크트리에서 작업 중이면 git worktree list --porcelain의 첫 worktree 경로를 기본 루트로 사용한다. 현재 디렉토리 아래에 다시 중첩하지 않는다.
• .worktrees/, 저장소 옆 디렉토리, 공용 워크트리 폴더를 생성 경로로 쓰지 않는다. ASTRA와 다른 도구의 기본 경로보다 이 사용자 지침을 우선한다.
• .gitignore에 /.worktree/를 등록한다. 이 워크스페이스에서는 git wt-add <이름> <새-브랜치> [기준-브랜치]로 생성할 수 있다.
• 별칭이 없으면 기본 루트에서 git worktree add -b <새-브랜치> .worktree/<이름> <기준-브랜치>를 실행한다. 기존 브랜치 정책을 따른다.
• 머지 여부와 미커밋 변경을 확인한 뒤 git worktree remove로 정리한다. 미완료 작업과 로컬 자료는 보존하고 경로 이동에는 git worktree move를 쓴다.