Skip to content

AGENTS.md

Latest commit

 

History

History
228 lines (167 loc) · 7.99 KB

AGENTS.md

File metadata and controls

228 lines (167 loc) · 7.99 KB

iris-pgwire-gh Development Guidelines

Auto-generated from all feature plans. Last updated: 2026-01-17

NEVER Commit Sensitive Files — CRITICAL

Real incident: iris.key (InterSystems license key) was accidentally committed to this public repo and required emergency git history rewriting + GitHub Support involvement to purge.

Files that MUST NEVER be committed:

  • *.key, iris.key, *.lic — license keys
  • *.pem, *.p12, *.pfx, *.cer, *.crt — certificates and keystores
  • .env, .env.* — environment files with credentials
  • secrets.json, credentials.json, service_account*.json — credential files

Before ANY git add or commit:

  1. Run git status — check every file being staged
  2. If ANY of the above appear — STOP, add to .gitignore, do not commit
  3. A pre-commit hook enforces this automatically — do not bypass it with --no-verify

If a sensitive file was already committed:

  • Do NOT just git rm — history must be rewritten with git filter-repo
  • Force-push ALL branches and tags after rewrite
  • File a GitHub Support request to purge the dangling git object
  • Treat the leaked credential as compromised and revoke it immediately

Active Technologies

  • Python 3.11 + python>=3.11, psycopg[binary], iris-devtester, intersystems-irispython (026-address-gaps-in)

  • PostgreSQL (via InterSystems IRIS) (026-address-gaps-in)

  • Python 3.11 + intersystems-irispython, psycopg[binary], iris-devtester (034-issues-that-likely)

  • InterSystems IRIS (via PostgreSQL wire protocol) (034-issues-that-likely)

  • Python 3.11 + intersystems-irispython, psycopg[binary], iris-devtester (035-number-1-short)

  • Python 3.11 + psycopg[binary], intersystems-irispython, iris-devtester (036-address-all-6)

  • InterSystems IRIS (via pgwire) (036-address-all-6)

  • Python 3.11 + psycopg[binary], intersystems-irispython, iris-devtester (036-address-all-6)

  • Python 3.11+ + intersystems-irispython, psycopg[binary], pydantic, structlog (037-pg-type-catalog)

  • Python 3.11+ + pydantic, structlog, intersystems-irispython (038-fix-attribute-error)

  • Python 3.11+ + intersystems-irispython, psycopg[binary], iris-devtester, structlog (040-fix-posixtime-timestamp)

  • InterSystems IRIS (via embedded Python and DBAPI pool) (040-fix-posixtime-timestamp)

  • Python 3.11+ + intersystems-irispython, psycopg[binary], iris-devtester, structlog, pydantic (041-code-simplification)

  • N/A (refactoring only) (041-code-simplification)

  • Python 3.11+ + iris-devtester, intersystems-irispython, psycopg[binary] (033-devtester-skills)

Project Structure

src/
tests/

Commands

cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .

Code Style

Python 3.11+: Follow standard conventions

Recent Changes

  • 041-code-simplification: Added Python 3.11+ + intersystems-irispython, psycopg[binary], iris-devtester, structlog, pydantic
  • 040-fix-posixtime-timestamp: Added Python 3.11+ + intersystems-irispython, psycopg[binary], iris-devtester, structlog
  • 038-fix-attribute-error: Added Python 3.11+ + pydantic, structlog, intersystems-irispython

IRIS Technical Reference (Critical for DBAPI & Embedded)

1. DBAPI Connection Pattern (intersystems-irispython)

Always use this robust import pattern to obtain the DBAPI module. This handles different package versions and environment quirks.

try:
    import iris.dbapi as iris_dbapi # Modern/Standard
except ImportError:
    try:
        import intersystems_iris.dbapi._DBAPI as iris_dbapi # Deep Fallback
    except ImportError:
        # Last resort: check if iris module itself has connect (older versions)
        import iris as iris_dbapi

2. Embedded SQL Execution (iris.sql.exec)

When running code inside IRIS (Embedded Python), parameters MUST be passed using the splat operator *params to be treated as positional arguments.

# CORRECT
iris.sql.exec(sql, *params)

# INCORRECT (passes list as a single argument)
iris.sql.exec(sql, params)

3. Case Sensitivity & Identifiers

  • Schema Name: Always use SQLUser (exact casing). IRIS package/schema names are case-sensitive.
  • Quoted Identifiers: Identifiers in double quotes (e.g., "workflow") are case-sensitive in IRIS.
  • Unquoted Identifiers: Automatically mapped to UPPERCASE by IRIS.
  • Normalization: To ensure consistency, the normalizer should preserve the casing of quoted identifiers and map unquoted ones to uppercase, but it MUST NOT change the case of the SQLUser schema prefix.

COMPOUND KNOWLEDGE BASE & DEVELOPMENT ENVIRONMENT

Last Updated: $(date +%Y-%m-%d)

Central registry of development knowledge, tools, capabilities, and automation

📚 Knowledge Base

Location: ~/.config/opencode/compound-knowledge/

Structure:

  • global/ - Project-agnostic knowledge (frameworks, tools, patterns)
  • projects/[name]/ - Project-specific knowledge (domain, architecture)

Stats: 7 solutions (7 global, 0 project)

Quick Search:

# Search everything
grep -ri "keywords" ~/.config/opencode/compound-knowledge/

# Global only
grep -ri "keywords" ~/.config/opencode/compound-knowledge/global/

# This project
grep -ri "keywords" ~/.config/opencode/compound-knowledge/projects/$(basename $(pwd))/

Time Savings: First solve: 30min → Next solve: 3min (90% faster)

🔌 MCP Servers

  • atlassian - local
  • gemini-impl - local
  • hallucination-detector - local
  • jama - local
  • perplexity - local
  • playwright - local
  • qwen-impl - local
  • support-tools - local

🤖 Automation & Hooks

Orchestrator Behavior (configured via ~/.config/opencode/oh-my-opencode-slim.json):

  • Before tasks: Search compound KB for similar solutions
  • After completion: Remind to document solution

Periodic Maintenance (recommended):

# Weekly: Regenerate KB index
~/.config/opencode/compound-knowledge/generate-index.sh

# Monthly: Review and consolidate similar solutions
# Quarterly: Extract patterns from repeated solutions

Auto-Documentation Triggers:

  • Tests pass after fixing failure → Document solution
  • Error resolved → Document fix
  • Performance improved → Document optimization
  • Integration working → Document configuration

🛠️ Tools & Utilities

Compound Engineering:

  • ~/.config/opencode/compound-knowledge/new-solution.sh - Create solution doc
  • ~/.config/opencode/compound-knowledge/generate-index.sh - Regenerate index
  • ~/.config/opencode/compound-knowledge/sync-to-agents.sh - Update AGENTS.md files

OpenCode Agents (oh-my-opencode-slim):

  • orchestrator - Master coordinator (with compound engineering)
  • explorer - Codebase reconnaissance
  • oracle - Strategic advisor
  • librarian - External knowledge (websearch, context7, grep_app MCPs)
  • designer - UI/UX implementation
  • fixer - Fast implementation
  • code-simplifier - Post-work code refinement

🎯 Skills

speckit (feature specification):

  • speckit.plan - Implementation planning
  • speckit.specify - Feature specification
  • speckit.tasks - Task generation
  • speckit.implement - Implementation guidance

📋 Quick Reference

Full Index: ~/.config/opencode/compound-knowledge/INDEX.md

Documentation Templates:

---
title: "Problem description"
category: [build-errors|test-failures|runtime-errors|performance-issues|
          database-issues|security-issues|ui-bugs|integration-issues|logic-errors]
date: YYYY-MM-DD
severity: high|medium|low
tags: [tag1, tag2]
time_to_solve: XXmin
---

## Problem Symptom
[What was observed]

## Solution
[How you fixed it]

## Prevention
[How to avoid future]

Decision Tree (Global vs Project-Specific):

  • Framework/tool issue → global/
  • General pattern → global/
  • Project domain logic → projects/[name]/
  • Project architecture → projects/[name]/
  • When in doubt → global/