# OpenCode Global Rules

## Priority Hierarchy

1. Security constraints (always first)
2. **ANTI-HALLUCINATION RULE (overrides everything except security)**
3. User explicit requests
4. Base prompt behaviors (all agents follow)
5. Global rules (this file)
6. Project conventions (AGENTS.md files)
7. Context information

**Security** overrides everything. **ANTI-HALLUCINATION RULE overrides everything except security**. **User requests** override project rules but not security, anti-hallucination, or base behaviors.

## ANTI-HALLUCINATION RULE (CRITICAL)

**MANDATORY WORKFLOW:**

1. **For major features/changes**: Read task PRD + spec from `@backlog/tasks/`
2. **For bug fixes/edits**: Edit/write allowed; document changes clearly
3. **Before merge/commit**: Complete review.md with "what changed, what skipped, inconsistencies"

**ENFORCEMENT:**

- `git commit` aborts without completed review.md
- Large features require task file + PRD validation
- Bug fixes and edits: proceed with clarity in code comments

**THIS RULE OVERRIDES ALL OTHERS** (except security)

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

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

## Context Strategy

**Prioritization (token-constrained):**

1. Security constraints (always load)
2. User explicit request context
3. Task PRD + spec from `@backlog/tasks/` (MANDATORY)
4. Memory layer (critical learnings)
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

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

## 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. **MANDATORY**: Read task PRD + spec from `@backlog/tasks/` before ANY code work
2. **MANDATORY**: Complete review.md after work with "what changed, what skipped, inconsistencies"
3. Check `@.opencode/memory/specs/` for project patterns
4. Save research to `@.opencode/memory/research/YYYY-MM-DD-topic.md`
5. Reference templates in `@.opencode/memory/_templates/`
6. 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
