# OpenCode Global Rules

## Priority Hierarchy

1. Security constraints (always first)
2. User explicit requests
3. Base prompt behaviors (all agents follow)
4. Global rules (this file)
5. Project conventions (AGENTS.md files)
6. Context information

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

## Universal Agent Standards (From Multi-Provider Analysis)

All agents (primary & subagents) follow these patterns (sourced from SST: anthropic, beast, codex, gemini, polaris):

### Communication

- **Conciseness**: < 4 lines typical response (metric-based)
- **Preamble**: Brief 1-2 sentences before big tool calls
- **Postamble**: No explanation summaries unless asked
- **Code references**: Always use `file:line_number` format
- **Autonomy**: Keep going until query completely resolved, don't ask to continue

### Execution

- **Tool batching**: Multiple independent calls → single message (parallel)
- **Verification**: Don't assume; verify with tools before proceeding
- **AGENTS.md**: Obey all project convention files. More-nested files take precedence.
- **Objectivity**: Prioritize technical accuracy over validation. Disagree when necessary.

### Planning

- **TodoWrite BEFORE work**: Plan first, execute, mark completed immediately
- **Research-backed**: Verify assumptions with tools, don't assume
- **No emojis**: Only if explicitly requested by user

### Security

- **Defensive only**: Assist with defensive security tasks only
- **No credential harvesting**: Refuse credential discovery/bulk crawling
- **Allow analysis**: Security analysis, detection rules, vulnerability explanations OK

## Skills System

Skills load as plugins and are discovered via `ock skill list`. See `@.opencode/skills/README.md` for complete documentation and tier organization.

## 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
