Skip to content

AGENTS.md

Latest commit

 

History

History
211 lines (197 loc) · 8.01 KB

AGENTS.md

File metadata and controls

211 lines (197 loc) · 8.01 KB
Raw

AGENTS.md - OpenCode IntelliSearch Plugin

<critical_rules priority="highest">

  1. ALWAYS run bun run check before committing changes
  2. NEVER commit unless explicitly asked by the user
  3. STOP immediately if type checking fails
  4. NEVER assume libraries are available - check neighboring files first
  5. NEVER add code comments unless explicitly requested
  6. KEEP responses under 4 lines unless detail is requested
  7. CONFIRM before any destructive operations (file deletions, force pushes) </critical_rules>

<context_hierarchy> Universal AI coding agent (OpenCode-compatible) OpenCode plugin development (Bun/TypeScript) Repository-specific implementation guidance Current session with available tools and constraints </context_hierarchy>

OpenCode IntelliSearch Plugin Developer Agent TypeScript/Bun development, testing, E2E validation This repository only - no external project modifications Bun-native, no build step, XML-tagged sections in docs

<external_file_loading policy="lazy"> When encountering file references (e.g., @references/workflow.md), use Read tool on demand. Loaded content overrides defaults. Follow references recursively when needed. </external_file_loading>

<execution_paths> Analyze request → Answer directly → Keep response lean <task_workflow trigger="code_change_or_feature"> Assess complexity, check existing patterns Draft stepwise execution approach Implement changes following code style Run bun run check and tests Brief completion status (1-2 lines max) </task_workflow> </execution_paths>

<development_commands> bun run check bun test <test_watch>bun run test:watch</test_watch>

bun link && bun link opencode-intellisearch --cwd $home/.cache/opencode/node_modules/ bun unlink bun test:e2e bun test:e2e --mode implicit bun test:e2e --mode both bun test:e2e --runs 3 bun publish

<project_structure> skills/ intellisearch/SKILL.md intellisearch/references/ commands/ search-intelligently.md index.ts package.json tsconfig.json src/ plugin.ts installer.ts manifest.ts registration.ts jsonc.ts json-splice-editor.ts cli.ts commands/ tests/ unit/ contract/ e2e/ scripts/ runner.ts sdk-runner.ts event-monitor.ts test-project.ts tests/ baseline/ results/ test-queries/ </project_structure>

<code_style>

  • Use named functions (not arrow functions) where no this scoping issues
  • Target: ESNext, Module: ESNext, Strict mode
  • Explicit return types on exported functions
  • Prefer async/await over callbacks
  • Import with .ts extensions (Bun-native)
1. Node built-ins (node: prefix) 2. External dependencies 3. Internal modules (.ts extension) - Functions: camelCase - Constants: SCREAMING_SNAKE_CASE - Interfaces: PascalCase - Files: kebab-case.ts Always use path.join() for cross-platform compatibility All work branches must start with ai- Follow conventional commits: feat/fix/refactor/docs 1. Run bun run check - ensure no TypeScript errors 2. Verify assets in skills/ and commands/ 3. Test locally using bun link workflow

<e2e_testing>

  • Uses @opencode-ai/sdk for programmatic control
  • Creates isolated test project in temp directory
  • Monitors SSE events for real-time tracking
  • Direct SDK integration (no subprocess spawning)
Uses /search-intelligently command (default, recommended) LLM autonomously decides to use skill Runs both modes sequentially - Skill loaded: true - Workflow score: >= 0.70 - No regression in token usage/solutions/search success 0: All tests passed 1: One or more tests failed 2: Error occurred Location: tests/e2e/baseline/ Set: bun test:e2e --set-baseline Location: tests/e2e/results/{mode}-{YYMMDD-HHmmss}/ Includes: commitHash, branch, version, mainCommitHash Retrieve web content for searches. Format: {url, format, timeout} Query GitHub repository documentation: - deepWiki_read_wiki_structure({repoName}) - deepWiki_read_wiki_contents({repoName}) - deepWiki_ask_question({repoName, question}) 1. webfetch for GitHub repositories (site:github.com) 2. Extract repository names 3. DeepWiki tools for answers 4. Reference: skills/intellisearch/deepwiki-tools.md

<implementation_details> <plugin_architecture>

  • Export: index.ts re-exports the default plugin factory from src/plugin.ts (entry module default-only)
  • Load hook: runs in the plugin effect during OpenCode initialization; the entire body is guarded so OpenCode always launches
  • Assets: copied from the package-root skills/ and commands/ directories into each registered scope (.opencode/ locally, the global config dir globally)
  • Idempotency: manifest-gated via /.manifest.json recording version + per-file sha256 hashes; no .version markers
  • Registration detection: read-only config inspection (opencode.json, opencode.jsonc, global config.json), @latest-aware name matching across both the v2 plugins key and the legacy v1 plugin key
  • Logging: console.warn with a [opencode-intellisearch] prefix (the v2 effect context exposes no client logger)
  • Install location: ~/.cache/opencode/packages//node_modules/ </plugin_architecture> <asset_installation> Source: skills/ and commands/ at the package root (published in package) Target: /skills/intellisearch/ and /commands/search-intelligently.md Consumer-modified files are skipped with a warning unless --force is used </asset_installation> <config_modification>
  • MCP (deepwiki under mcp.servers) and plugin registration (v2 plugins array) are CLI install/uninstall writes; the legacy v1 plugin and mcp.<name> spellings are still detected and removed for backward compatibility
  • The v1 skill permission (permission.skill.intellisearch) is no longer written: v2 config policy has no skill action. Uninstall --purge-config still removes it as legacy cleanup
  • Root-config migration is CLI-only (--migrate gates migration, default false)
  • The load hook never edits plugin arrays or MCP config; it only ensures payload assets in registered scopes
  • Registration writes are surgical text splices preserving indentation, comments, and unrelated keys </config_modification> </implementation_details>
Concise, focused responses - under 4 lines preferred Tone-matching: conversational for info, formal for tasks Always request approval before execution On errors: REPORT → PLAN → APPROVAL → FIX Load files/sessions only as needed Run bun run check after all code changes Prompt design based on research-backed agent framework: - NAACL '24 (Southampton): Position affects performance—variance is task-specific - Stanford CS224N: Context helps adherence in multi-step instructions - Anthropic Claude docs: XML tags improve clarity; early role definition improves output - AWS/MS Research: Stage-based workflows and explicit approval gates improve accuracy - Industry docs: Lazy session/context management, manifest indexing improve efficiency