Imported from duyhxm/anki-automation (AGENTS.md). Install upstream with npx skills add duyhxm/anki-automation. Copyright stays with the author.

Anki Automation — OpenCode Agent Configuration

This project uses OpenCode as the canonical AI coding agent. Configuration lives under .opencode/.

Project Overview

English vocabulary flashcard automation tool. Converts structured JSON vocabulary data into high-quality Anki flashcards. Output: .apkg file (genanki) or direct AnkiConnect import.

Core Architecture

• 3-Layer Pipeline: 1) Validate + Enrich, 2) Transform + Render, 3) Package + Import.
• Schema-First: Pydantic v2 models with discriminated unions (schema.py).
• Plugin Backends: genanki (primary, offline .apkg), AnkiConnect (optional, --live).
• 24-Field Note Type: EnVocab_B2 with Note_ID, Vocabulary, Meaning_VI, IPA, Audio, POS, Register, Countability, Transitivity, Usage_Note, Examples, Patterns, Collocations, Synonyms, Antonyms, Categories, POS_Metadata, CEFR, Frequency_Score, Image, 3×Cloze fields.

Agent Team

The project uses a single primary agent + specialist subagents model. The human interacts only with @pipeline-engineer. Pipeline-engineer handles ALL planning, design conversations, code changes, and subagent coordination.

Primary Agent (Tab-switchable — ONLY ONE)

Specialist Subagents (invoked via Task tool or @mention)

Workflow Summary

Human → @pipeline-engineer → Design conversation → Implement → Verify → Commit
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
              schema-guardian  ui-designer    debugger
              (schema review)  (UI design)   (diagnostics)

For subagent delegation, use the Task tool with a clear prompt describing the work needed and expected output.

Python and Tooling

• Python 3.12 with uv (mandatory). Never use pip, poetry, or raw venv.
• Install: uv sync. Add dep: uv add <pkg>. Run script: uv run python <script>.py.
• Dev tools are in dev dependency group:
  • Lint: uv run ruff check .
  • Typecheck: uv run mypy . (future)
  • Test: uv run pytest (future)

Rules and Instructions

Detailed rules are loaded from .opencode/rules/:

• core.md — Project-wide conventions, module boundaries, quality gates
• python-style.md — Naming, types, imports, anti-patterns
• contracts.md — Schema mapping, validation boundaries, field value rules
• workflow.md — Common task guides (add field, change template, debug)

Available Skills

Load these project-specific skills via the skill tool:

• gitnexus-exploring — Explore codebase structure, trace execution flows
• gitnexus-impact-analysis — Blast radius before editing code
• gitnexus-debugging — Trace errors, diagnose failures
• gitnexus-refactoring — Safe rename, extract, restructure operations

Custom Commands

• /lint — Run ruff linter
• /typecheck — Run mypy type checker
• /test — Run pytest
• /check — Syntax check all Python files
• /setup — Create or update note type in Anki
• /import — Import data.json into default deck

Rules for Agents

1. Never edit schema.py without explicit user request. It is the data contract.
2. Read before write. Always read existing code to understand conventions before editing.
3. Match existing style. Follow patterns in neighboring files — naming, imports, structure.
4. No comments. Code should be self-documenting. Only add comments for non-obvious logic.
5. Type hints on ALL functions. Use str | None, not Optional[str].
6. After every code change: at minimum, syntax check (/check). If templates changed: --setup.
7. Anki must be running for AnkiConnect operations. Check with curl localhost:8765.
8. Check .gitignore before committing. Never commit uv.lock, .venv/, .mp3 files.
9. Before commit: verify git status, run lint, confirm no unrelated changes.

Version Bumping (for README/CHANGELOG)

This project follows SemVer. After feature releases, update pyproject.toml version and CHANGELOG.

GitNexus Code Intelligence

The project is indexed by GitNexus. Use gitnexus_* tools when:

• Exploring unfamiliar code → gitnexus_search + gitnexus_explore
• Analyzing impact before changes → gitnexus_impact
• Debugging errors → gitnexus_query
• Refactoring → gitnexus_rename

Communication Language

• With humans: Vietnamese by default. English only for specialized technical terms.
• In source code, comments, config files, logs: English exclusively.