AGENTS.md

Generated by scripts/sync-agent-instructions.sh (WP-394 Phase4.2). DO NOT EDIT MANUALLY. Shared core → <!-- SYNC-CORE --> block in CLAUDE.md. Agent-specific content → AGENTS-agent-blocks.md.

WP Gate — CRITICAL

ANY task → Opening Protocol → BEFORE starting work. When creating a new Work Product: declare the Role, work, Work Product, verification class, Method, Assessment, and model. Wait for pilot confirmation.

State-Transition Gate — CRITICAL

If {{GOVERNANCE_REPO}}/docs/state-axes-registry.yaml exists → before any non-trivial action or Work Product, read and execute .claude/rules-lazy/state-transition-gate.md in full; if the lazy file is absent or unreadable → inventory only, STOP. If the registry does not exist → gate is inactive.

Git Staging — CRITICAL

NEVER git add -u, git add ., git add -A — these pick up changes from OTHER agents (Kimi/Hermes run in parallel) → incorrect attribution. Stage only specific files; before committing run git diff --cached --name-only and unstage anything unintended with git restore --staged. Examples → memory/reference/agent-core.md.

After git mv in the same Work turn — verify content, not just the filename (issue #511). The name list from --name-only may look correct while the diff is empty (rename without edits) or stale (edits made via Edit went to the wrong path). If a git mv of any file being committed occurred in this Work turn: run git diff --cached <new_path> before git commit and confirm the intended changes are present; commit only the new path after git mv, not the old one; separately verify the return code of git add before proceeding to git commit.

Artifact Naming

Do not invent artifact names. Names for sections, documents, Work Products, and deliverables must come from the plan/task you received. If the task is silent on a name — report "need clarification on name" instead of making one up.

Drift Reporting

Discrepancy found (file ≠ plan, stale content): report to pilot, do not silently fix. Format: "Found drift: [what] in [file]. Should I fix it?" Fix only if explicitly instructed.

Working Directory

{{WORKSPACE_DIR}}/

FPF Usage

Work relies on FPF/DPF → use the /fpf Skill (Step 0 reads the author's instructions (file USING-FPF.md in the FPF copy) and verifies the full text). Full text is absent → tell the user and do not produce output that depends on it; include in the response: copy version, pattern numbers, assumptions.

Status Reporting — Agent Status Registry (WP-395)

Primary (required): at the start of a task call agent_status_update(agent=<claude-code|kimi|codex|hermes>, status=working, task=<brief>, files=[...]); on completion — status=idle. Statuses: idle|working|peer-session|blocked; the pilot sees all agents via agent_status_list. Team mode (repo=) and fail-safe Script → memory/reference/agent-core.md.

Long Operation Protocol — 180 s Silence Threshold

Do not go silent for more than 180 seconds. For an operation >180 s → BEFORE launching it, report: what is being launched, duration, step X of Y, background task id. If >180 s of silence occur → send a micro-report: "Still working. Current step: [X of Y]. Next: [Z]." This applies to everything where the pilot sees an empty "Thinking" state (bash, subagent, background tasks, Close protocols).

WP-REGISTRY Naming — CRITICAL

The "Name" column in WP-REGISTRY contains ONLY the Artifact name ≤80 characters — no dates, session references, metrics, SHA values, or other metadata.

Where to put everything else: Closing summary → ## Closing in archive/wp-contexts/; phases/Progress → frontmatter inbox/WP-NNN/WP-NNN.md (always a folder — WP-434); when phase status changes, update the frontmatter, NOT the registry name. Full text and ✅/❌ examples → memory/reference/agent-core.md.

WP Context Scope — Umbrella Work Product

Umbrella Work Products with agent_scope: open-only (WP-5, WP-7) — read only phases with status pending/in_progress/blocked; do not read archived phases without an explicit user request.

Calendar Events — CRITICAL

All agent-created reminders and calendar events must be scheduled BEFORE 09:00 AM (later only with explicit pilot approval). Created after 09:00 by mistake → delete + recreate before 09:00 + notify the pilot (steps → memory/reference/agent-core.md).

Language

Respond in Russian unless the user writes in English.

Response Style — Pilot-Facing

Rules for clear responses to the pilot (full text — memory/feedback_response_clarity_for_pilot.md) — applies to chat, report synthesis, and post-action reports.

Channel detector: technical style — peer-Session transcripts, commit messages, PRs; plain language — chat with the pilot (unless the pilot themselves writes grep/git/paths/SHA) and §1–§4 of the report.md synthesis.

Eleven rules (A1–A11), short: A1 file path is not the subject (parenthetical only, after a plain-language verb); A2 English term only after its Russian description in parentheses; A3 first mention of a column/function — one-word explanation; A4 pre-flight: will the pilot be able to make a decision based on this sentence; A5 WHAT before HOW; A6 one consequence arrow per sentence; A7 "did → effect", <details> only when pilot-relevant details exist or are explicitly requested; A7.1 process log (SHA, commits, defects) — to the report file only, not to chat; A8 do not write a process log by default; A9 channel detector; A10 English status markers (exit/PASS/SHA) → plain-language words; A11 active voice on errors and findings.

Code Style — Engineering (DP.SC.172)

P-rules, short: P0 before committing — run the repo's formatter and linter (tooling handles the mechanics); P1 a test without verifying an observable result is forbidden (assert True — code smell); P2 third repetition → extract a function, not locals()[str]; P3 dead branch/enum — delete it, do not keep "for compatibility"; P4 except: pass without logging is forbidden; P5 long function with mixed responsibilities / boolean mode flags — split it. Boundary: hard prohibitions (git add -A, secrets) belong in PACK-agent-rules (AR.*), not here. (Delivery/detectors per agent → memory/reference/agent-core.md.)

Constructive Implementation Identity — CRITICAL

The model is not the authoritative source of its own identity: self-report ("who are you?") is unreliable — documented case 06.08: Kimi K2 in a user installation identified itself as Claude (training data contains Claude texts). Identity is defined by THIS block and the launch tool, not by the model's guess about itself.

When asked about your identity, answer from this table and the actual launch channel — not from general knowledge about who most commonly writes such instructions. Personality (Elar/Kir/Koris/…) is a separate layer on top of the implementation: it is defined by the personality Registry and passport, not by this block or the model.

Commit Attribution

Co-Authored-By is added only by an agent that actually participated in creating the commit (authorship, Review, substantive edit). Autonomous commits by other agents / Scripts — no trailer, if the agent did not participate.

If an agent only verified (checked) a commit — use Verified-by: [Agent] <[email]> or a "Verified by [role]" note in the commit body, not Co-Authored-By.

For commits involving Kimi

Method 1 (preferred — template):

git commit -t ~/.git-commit-template-kimi -m "feat: description"

Method 2 (manual — if template unavailable):

git commit -m "feat: description" --trailer "Co-Authored-By: Kimi <noreply@moonshot.ai>"

Never commit without the trailer. If you forget — amend immediately:

git commit --amend --trailer "Co-Authored-By: Kimi <noreply@moonshot.ai>"

For commits involving Codex (OpenAI)

git commit -m "feat: description" --trailer "Co-Authored-By: Codex <noreply@openai.com>"

Codex reads AGENTS.md natively; in peer sessions it acts as a critic (Review without file edits → Analyzed-by: Codex <noreply@openai.com>, following the same "editor vs. analyst" rule as Claude).

For commits involving Hermes (Nous Research)

git commit -m "feat: description" --trailer "Co-Authored-By: Hermes <noreply@nousresearch.com>"

Hermes Agent — orchestrator in the IWE ecosystem (WP-392). Connected to Aisystant MCP, operates via CLI/Telegram. Hermes does NOT replace Claude Code or Kimi Code for coding — it coordinates, retains Memory, and provides mobile access.

IWE Instructions Level (Kimi headless)

IWE workspace with 5000+ docs and multiple Packs — use experienced level.

Revisit if a new small repo (< 1000 docs) is added to {{HOME_DIR}}/IWE/.

When calling get_instructions (Aisystant MCP) to load IWE context, use level="experienced" instead of the default level="full". This reduces token load by ~89% (~10K → ~1.1K) on every headless turn.

Example:

get_instructions(level="experienced")

This applies to all Kimi sessions: peer (via kimi-peer-adapter.sh) and standalone. Determination basis: get_user_context() document_count ≥ 5000 + multiple Packs.

Coordination Protocol (MCP Gateway)

For agents with access to Local Gateway (Claude Code, Kimi). Hermes does NOT have MCP Gateway (acquire_file_lock / release_file_lock) — it uses terminal + patch directly, and reports to the pilot on push conflicts.

Before starting any edit task:

1. Declare intention (no lock needed):

   Tool: update_peer_status
   params: { "status": "working", "current_task": "<brief>", "files": ["relative/path/file.md"] }

2. Acquire lock before first Edit:

   Tool: acquire_file_lock
   param: canonical_file = relative path from IWE root

3. Release lock after commit:

   Tool: release_file_lock

4. On lock_collision: wait 30s and retry, or switch to another file.

Hermes Agent — Coordination

If Hermes Agent is present in the ecosystem (orchestrator with persistent Memory, WP-392):

• Hermes does NOT replace Claude Code / Kimi Code for coding — it coordinates, retains Memory, and provides mobile access.
• Hermes does NOT have MCP Gateway (acquire_file_lock / release_file_lock) — it edits files via terminal + patch.
• When editing critical files: git pull first, check git status, then edit; on push conflict — notify the pilot.

Prompt Cache Pattern

• PREFIX/BODY/TAIL pattern for headless agents → see memory/sota-prompt-cache.md.
• Apply when assembling the system prompt for a multi-turn agent: stable content (identity, rules) → PREFIX/BODY before the cache breakpoint; volatile content (Memory, timestamp) → TAIL.