sean2077_obsidian-dynamic-theme-background/AGENTS.md

Dynamic Theme Background — Agent Contract

Project essentials

Dynamic Theme Background is a TypeScript/CSS Obsidian community plugin for desktop and mobile. Keep this file as the concise behavior contract; use the development guide for architecture, change maps, manual checks, and release details.

• Treat src/ and styles.css as authored runtime sources; main.js is generated by esbuild, ignored by Git, and published only as a release asset.
• Preserve cross-platform support (manifest.json has isDesktopOnly: false); Node/Electron-only behavior requires an explicit, guarded desktop boundary.
• Keep src/plugin.ts as the lifecycle and composition root; background transitions, scheduling, styling, persistence, and internal events belong in the focused services under src/core/.
• Keep setting types, defaults, UI, persistence compatibility, and both source locale files aligned when configuration changes.
• Keep provider credentials and custom-header values in Obsidian SecretStorage: persist only references, migrate legacy plaintext all-or-retain, and hydrate isolated runtime config clones.
• Let semantic-release own normal version synchronization across manifest.json, package.json, package-lock.json, and src/version.ts; do not manually bump them outside a release task.
• When minAppVersion increases, preserve the last compatible release in versions.json so older Obsidian clients can fall back safely.
• Run npm run check for the complete automated gate; use npm test, npm run build, npm run lint, or npm run lint:css for focused iteration. Record the relevant manual Obsidian checks for behavior changes that require a real app, theme, or device.

Agent Harness (Claude Code + Codex)

This repo carries a vendored, dual-host agent harness. .agents/ is the single source of truth (SSOT); .claude/ and .codex/ are wired to the same implementations under .agents/tools/.

Worktree-per-change (hard rule)

Never edit trunk (main) directly — every change, however small ("just docs" is NOT an exception), starts in its own worktree cut from the trunk tip:

bash .agents/tools/worktree.sh new <name>   # edit inside .worktrees/<name>/  (branch feat|fix|docs|chore/<name>)
bash .agents/tools/worktree.sh done         # merge back to local trunk (--no-ff) + clean up + ff-only push

.agents/tools/hooks/trunk_edit_guard.sh (PreToolUse) mechanically blocks edits to tracked files while on trunk. Escape hatch — only when the user explicitly authorizes a trunk edit: touch .claude/allow-trunk-edit (auto-expires in 2 h) or WORKTREE_ALLOW_TRUNK_EDIT=1.

Authority documents (hard rules)

AGENTS.md is the canonical repository-level contract for Agent work. Read and follow the root contract and its applicable nested contract chain before acting; higher-priority instructions still govern.

• Keep it current. When a durable change affects an Agent-relevant command, invariant, ownership boundary, risk boundary, or navigation path, update or remove the affected contract guidance in the same change. If the detail lives in linked project docs, update it there and keep the contract summary and link accurate.
• Keep it lean. Keep only concise, actionable guidance that changes Agent behavior and is frequently needed or costly to miss. Move explanations, rationale, history, long procedures, examples, and low-frequency detail to project docs and link to it.
• Keep scopes honest. Root rules are project-wide. Create a nested AGENTS.md only for a concrete local difference from the nearest ancestor; directory structure alone never justifies one.
• Resolve conflicts explicitly. If applicable instructions conflict, or contract guidance disagrees with verified repository facts, do not guess or silently ignore either. Surface the conflict, follow higher-priority instructions, request owner direction when authority is unclear, and repair stale guidance in the same change when authorized.

The authority-document budget hook remains advisory; projects may override its default line and character limits when justified.

SSOT layout

Path	Role	Commit?
.agents/skills/<name>/SKILL.md	project skill source	✅
.agents/subagents/<name>/{metadata.json,instructions.md}	subagent source	✅
.claude/skills/<name>	symlink → .agents/skills/<name> (CC discovery; Codex reads .agents/ directly)	✅
.claude/agents/*.md, .codex/agents/*.toml	generated subagent projections — do NOT hand-edit	✅
.agents/tools/hooks/	scaffold-managed hook runtime (doc budget + optional trunk guard)	✅
.agents/tools/worktree.sh	worktree lifecycle	✅
.claude/allow-trunk-edit	worktree escape hatch	❌ ignored
.claude/settings.local.json	personal overrides	❌ ignored

• Add a skill: edit .agents/skills/ → run bash .agents/relink-skills.sh → commit source + symlink.
• Add a subagent (needs python): edit .agents/subagents/ → run python .agents/tools/generate-subagents.py → commit source + generated. Wire --check into the project's own CI or hook manager when desired.
• Third-party skills follow project-owned placement and installation policy. The relinker manages only names sourced from .agents/skills/, preserves unrelated entries, and fails on same-name ownership conflicts.

Codex trust: project-level .codex/ (config + hooks + agents) only loads for a trusted project; until trusted it is silently skipped. Trust once: run codex here and accept, or add [projects."<repo abs path>"] trust_level = "trusted" to ~/.codex/config.toml.