anidachi-LP

Imported from AniDachi/anidachi-LP (AGENTS.md). Install upstream with npx skills add AniDachi/anidachi-LP. Copyright stays with the author.

AGENTS.md

This file is the short startup contract for AI and human contributors working on AniDachi. Keep it concise. Put long explanations in docs/.

Read First

Before making product changes, read these in order:

1. docs/project-operating-manual.md
2. docs/current-development-state.md
3. docs/project-architecture-and-development.md
4. The relevant active plan in docs/superpowers/plans/

For room, realtime, or P2P work, also read:

• docs/superpowers/plans/2026-06-07-production-room-p2p-hardening-roadmap.md
• docs/superpowers/plans/2026-06-12-room-flow-p2p-flawless-execution-plan.md

For development-process work, read:

• docs/superpowers/plans/2026-06-17-development-flow-quality-system-plan.md

For quality-gate decisions, read:

• docs/development-quality-gates.md

Instruction Layers

This root file contains stable project-wide rules. Subdirectories can add tighter rules for their own plane:

• apps/web/AGENTS.md
• apps/api/AGENTS.md
• apps/extension/AGENTS.md
• packages/protocol/AGENTS.md

Keep changing product facts in canonical docs such as docs/current-development-state.md, active plans, ADRs, or domain docs. If an existing rule blocks the right architecture, explain the conflict and update the rule/docs instead of bypassing it silently.

Git Flow

Normal flow:

feature/codex branch -> PR -> staging -> tested promotion PR -> main

Rules:

• Branch from latest staging.
• Open PRs into staging first.
• Never push directly to main.
• Never force-push staging or main.
• Do not revert unrelated user or collaborator changes.
• Production promotion happens only after staging acceptance for risky work.

Startup commands:

git fetch origin
git switch staging
git pull --ff-only origin staging
git switch -c codex/task-name
fnm use --install-if-missing
corepack enable
corepack prepare pnpm@11.2.2 --activate
pnpm install --frozen-lockfile

If an automated shell does not source the local zsh/fnm setup, prefix project commands with fnm exec --using="$(cat .node-version)".

Project Planes

• apps/web: durable product state, auth, OAuth callbacks, rooms, Supabase, Stripe, invite/join pages, SEO, internal CRM tools.
• apps/api: Cloudflare Worker, Durable Objects, WebSocket room state, live sync, P2P signaling, ICE/TURN access.
• apps/extension: WXT Chrome extension, content scripts, overlay, video adapters, WebRTC media, push-to-talk.
• packages/protocol: shared room/event schemas and sync contracts.

If behavior crosses planes, define the protocol/contract first. Changes to room events, snapshots, auth handoff, invite flow, playback sync, P2P signaling, subscription entitlements, or shared payloads usually require checking packages/protocol and all affected consumers before implementation is considered complete.

Quality Gates

Use docs/development-quality-gates.md to decide which checks, staging evidence, docs updates, and Graphify updates are needed for a change.

Before opening a PR, run:

pnpm dev:check

Record docs status, Graphify status, staging impact, and rollback notes in the PR template. Small docs-only changes should not trigger heavy runtime checks, but high-risk auth, billing, API, extension, protocol, room/P2P, deploy, or env exceptions must be documented.

Commands

Baseline:

node --version   # repo .node-version: 22.23.1
pnpm --version   # repo expects pnpm 11.2.2
pnpm check
pnpm test
pnpm dev:check

Web:

pnpm --filter @anidachi/web check
pnpm --filter @anidachi/web test
pnpm dev:web

API / Worker:

pnpm --filter @anidachi/api check
pnpm --filter @anidachi/api test
pnpm harness:rooms
pnpm smoke:worker:staging

Extension:

pnpm --filter @anidachi/extension check
pnpm --filter @anidachi/extension test
pnpm build:extension:staging
pnpm validate:extension:staging

Real WebRTC harness:

npm --prefix tests/e2e install
npm --prefix tests/e2e exec playwright install chromium
npm --prefix tests/e2e run harness:p2p

Serena Code Navigation

When Serena is available, use it for symbol definitions and references. Use Graphify for broad architecture and normal text search for filenames, text, configuration, and exact error messages. Neither replaces source review or tests.

Before the first Serena code query in a task, and after changing worktrees:

• Resolve the current checkout with git rev-parse --show-toplevel.
• Read Serena's initial_instructions, activate that exact absolute path, and verify the active project with get_current_config. Do not activate by the shared project name or assume the main clone is the task's checkout.
• Keep Serena limited to reading/navigation. Apply approved changes with normal Codex editing tools. Do not run onboarding or create a second project memory.
• If references look incomplete, check dependencies and TypeScript readiness, then verify with source/text search. An empty result does not prove no callers.

Portable settings live in .serena/project.yml; caches and local overrides are ignored. See docs/serena-codex-setup.md for host setup and verification.

Knowledge Graph

Graphify is the local project knowledge graph. Use it before broad architecture, auth, room, P2P, Worker, CI, or release-flow changes.

Setup per machine:

uv tool install --upgrade graphifyy
graphify install --project --platform codex
pnpm graph:baseline
pnpm graph:hook:uninstall
pnpm graph:hook:status
pnpm graph:merge-driver:install

Codex must have multi_agent = true under [features] in ~/.codex/config.toml for full $graphify semantic extraction.

Daily use:

graphify query "Trace room token flow from web to Worker WebSocket join."
pnpm graph:update:code
pnpm graph:query "Trace room token flow from web to Worker WebSocket join."

For changed docs, plans, images, PDFs, or other semantic inputs, invoke $graphify . --update inside Codex instead of the code-only CLI command.

Rules:

• If graphify-out/graph.json exists, query it before doing wide file reads for architecture questions.
• Commit only team graph artifacts from graphify-out/: graph.json, GRAPH_REPORT.md, and manifest.json.
• Do not commit graphify-out/cost.json, HTML exports, scoped scratch graphs, cache files, Obsidian/wiki exports, or other local generated files.
• Git hooks are not installed by default because they dirty graphify-out/ during normal checkout/commit work. Use pnpm graph:update:code manually after meaningful code-only changes. pnpm graph:watch and pnpm graph:hook:install are local opt-ins only.
• .gitattributes marks graphify-out/graph.json for Graphify's merge driver. Run pnpm graph:merge-driver:install once per clone.
• $graphify . in Codex uses the active Codex session and does not require a separate LLM backend key. Headless pnpm graph:extract is different: it needs a configured backend when docs, PDFs, or images are present.
• In Codex, semantic extraction must use the Graphify skill and Codex subagents. Do not suggest or request Gemini or other provider keys unless the user explicitly asks for a headless or CI extraction backend.
• Record useful Graphify queries in PRs for room/P2P/auth/Worker/CI changes.
• Treat Graphify as navigation help. Verify important claims against source.

Safety Rules

• Do not commit secrets, .env*, .dev.vars*, debug exports, extension zips, generated extension folders, local browser profiles, or local-only graphify-out/ outputs.
• Staging must stay password-gated, noindex, excluded from sitemap, and absent from production SEO/marketing pages.
• Store-safe extension builds must keep narrow host permissions. Broad extension permissions are local-only.
• The extension must never receive service-role keys, OAuth secrets, JWT signing secrets, Stripe secrets, Cloudflare API tokens, or TURN secrets.
• AI-generated code is untrusted until tests, review, and project-specific checks pass.

Done Means

Docs-only:

• Documentation links remain accurate.
• Active docs do not contradict docs/current-development-state.md.
• PR records whether Graphify/docs updates were needed.

Site/UI:

• Relevant web checks pass.
• Visual behavior is inspected on the correct environment.
• Screenshots or a short recording are attached when useful for review.

Auth/API/payments:

• Unit/API checks pass.
• Env and secret impact is documented.
• Staging smoke is run where applicable.
• Protocol and runtime consumers are checked when payloads cross planes.

Extension:

• Extension check/test pass.
• Staging artifact is built and validated if behavior changed.
• Permissions remain channel-appropriate.
• Loaded-artifact or browser verification is recorded for user-visible changes.

Room/P2P/Worker:

• API tests and room harness pass.
• Real-WebRTC harness or staging manual test is used for media changes.
• Progress is recorded in the active P2P plan.

Release/deploy:

• CI status is understood.
• Rollback path is known before promotion.

graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

When the user types $graphify in Codex (or /graphify on another supported assistant), use the installed Graphify skill before doing anything else.

Rules:

• For codebase questions, first run graphify query "<question>" when graphify-out/graph.json exists. Use graphify path "<A>" "<B>" for relationships and graphify explain "<concept>" for focused concepts.
• Dirty graph files are not a reason to skip Graphify, but do not include graphify-out/ in ordinary feature PRs unless the graph was intentionally refreshed.
• If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
• Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
• After code-only changes, run pnpm graph:update:code (AST-only, no LLM or provider key).
• After docs, plans, images, PDFs, video, or other semantic corpus changes, run $graphify . --update inside Codex. Do not substitute graphify update . or pnpm graph:update:code, because those commands intentionally update only the code graph.
• Codex-hosted semantic extraction uses the active Codex session and subagents. It requires multi_agent = true, not a Gemini/OpenAI/Anthropic API key. Do not suggest provider keys unless headless or CI extraction was explicitly requested.