# OpenCode Global Rules

## Priority Hierarchy

1. Security constraints
2. User explicit requests
3. Base Prompt behaviors
4. Global Rules (this file)
5. Project conventions
6. Context information

Security overrides everything. User requests override project rules but not security or base behaviors.

## Skills System

**Skills are organized into 3 tiers** based on usage frequency:

```
Tier 1: CORE (9 skills) - Always loaded at session start
Tier 2: STACK (7 skills) - Context auto-load (file types, patterns)
Tier 3: SPECIALIZED (9 skills) - Manual activation only
```

### Tier 1: Core Skills (Always Available)

**Location:** `@.opencode/skills/core/`  
**Auto-load:** Session start  
**Count:** 8 skills

Essential workflow infrastructure used every session:

- memory, code-review, debugging, problem-solving
- sequential-thinking, docs-seeker, databases, devops

### Tier 2: Stack Skills (Context Auto-load)

**Location:** `@.opencode/skills/stack/`  
**Auto-load:** File types, tech stack detection  
**Count:** 7 skills

Common in modern solo dev stacks (2-4x/week usage):

- web-frameworks, frontend-design, better-auth
- document-skills, ai-multimodal, media-processing, prompt-engineering

**Auto-load Triggers:**

- `.tsx`, `.jsx` → frontend-design, web-frameworks
- `.sql`, `.prisma` → databases
- `Dockerfile`, `.github/workflows` → devops
- `.mp4`, `.png`, `.jpg` → ai-multimodal
- `prompts/`, `AGENTS.md` → prompt-engineering

### Tier 3: Specialized Skills (Manual Only)

**Location:** `@.opencode/skills/specialized/`  
**Auto-load:** Manual activation  
**Count:** 9 skills

Project-specific or episodic use:

- Framework-specific: htmx-spring-boot, shopify, thymeleaf
- Tool builders: mcp-builder, skill-creator, repomix
- Dev tools: chrome-devtools, google-adk-python

**Discovery:** See `@.opencode/skills/README.md` for complete tier documentation.

## Memory System

**Managed by:** `.opencode/memory/` skill (workflow orchestration)

**Location:** All memory files in project-local `.opencode/memory/`

**Files:**

- `@.opencode/memory/memory.md` - Active session context
- `@.opencode/memory/development-guidelines.md` - Code conventions
- `@.opencode/memory/architecture-decisions.md` - Design constraints
- `@.opencode/memory/blockers.md` - Known issues
- `@.opencode/memory/todo.md` - Task tracking
- `@.opencode/memory/handoffs/` - Phase transition bundles
- `@.opencode/memory/research/` - Research findings
- `@.opencode/memory/_templates/` - Document templates

**See:** `@.opencode/skills/core/memory/SKILL.md` for complete workflow integration.

## Context Strategy

**Prioritization (token-constrained):**

1. Security constraints (always load)
2. User explicit request context
3. Memory layer (critical learnings)
4. Backlog/task context
5. Codebase exploration (on-demand)

**Refresh Triggers:**

- Re-read if file modified in session
- Re-read memory after major changes
- Never re-read unchanged files

**Isolation:**

- All project context stored in `.opencode/` (project-local)
- No dependency on global `~/.config/opencode/` paths
- Each project is self-contained and portable
- Can clone/share entire opencodekit-template with teams

## Agentic Workflow System

**Two-Layer Architecture:**

```
Memory (Persistent) → Backlog (Multi-session) → Git (Audit Trail)
@.opencode/memory/     @backlog/tasks/          .git/
Permanent context      Days-weeks work          Execution history
```

**See:** `@.opencode/INTEGRATION_OVERVIEW.md` for complete architecture and integration patterns.

## Phase Transitions

Use `/handoff "next phase instructions"` custom command to create clean context bundles for intentional phase transitions.

**Manual Handoff** — Explicit Phase Boundaries

- Create portable, self-contained context bundles with `/handoff` command
- Includes: Phase summary, key decisions, relevant files, constraints
- Clean slate for next agent/phase without conversation pollution
- Data minimization: Only essential knowledge flows forward
- Use for: Research → Planning, Planning → Implementation, etc.

**When to Use:**

- Completing distinct work phase (research, planning, implementation)
- Handing off to different agent or team member
- Need clean separation without conversation history bleed
- Creating portable context for cross-workspace handoffs

**How It Works:**

1. Complete work phase (e.g., research findings, architecture plan)
2. Trigger: `/handoff "next phase instructions and goals"`
3. Creates: `.opencode/memory/handoffs/YYYY-MM-DD-{phase-name}.md`
4. Next phase: Open new thread, reference `@.opencode/memory/handoffs/...`
5. Result: Clean transition with essential context, no pollution

**Example:**

```bash
# After research phase
/handoff "design the rate limiting system based on research findings"

# Creates: .opencode/memory/handoffs/2025-11-20-rate-limiting-design.md
# Next thread: @plan agent with @.opencode/memory/handoffs/2025-11-20-rate-limiting-design.md
```

## Knowledge Base Integration

**Central:** `@.opencode/memory/`

**Structure:**

```
@.opencode/memory/
├── _templates/          # Document templates
├── research/            # Research findings (YYYY-MM-DD-topic.md)
├── specs/               # Task specifications
├── handoffs/            # Phase transition bundles
├── architecture-decisions.md
├── development-guidelines.md
├── memory.md
├── blockers.md
└── todo.md
```

**Requirements:**

1. Check `@.opencode/memory/specs/` before generating code
2. Save research to `@.opencode/memory/research/YYYY-MM-DD-topic.md`
3. Update specs when architecture drifts
4. Reference templates in `@.opencode/memory/_templates/`
5. See `@.opencode/INTEGRATION_OVERVIEW.md` for workflow integration patterns

## Core Constraints

- No sudo (escalate config changes)
- POSIX compatible (macOS/Linux)
- Manual verification for config changes
- Verify anchor uniqueness before edits
- No assumptions about files/URLs/libraries
- NO auto-documentation without request
- Use absolute paths for file operations
- Reasoning mode: OpenCode handles automatically
