Workspace Rules

Nyzhi automatically detects your project root and loads instruction files (rules) that shape agent behavior. These rules are injected into the system prompt, so the agent follows your team’s conventions from the first message.

Project Root Detection

When Nyzhi starts, it walks up from the current directory and stops at the first match:

1. .nyzhi/ directory
2. .claude/ directory
3. .git marker
4. Falls back to the current directory

Config Source

Based on what’s found, Nyzhi classifies the project:

Rule Loading

Rules are the instruction files that get injected into the agent’s system prompt. They’re loaded in a specific priority order.

Primary Rule File

Nyzhi checks these files in order and uses the first non-empty one:

1. AGENTS.md
2. .nyzhi/rules.md
3. .nyzhi/instructions.md
4. CLAUDE.md
5. .cursorrules

This means if you have both AGENTS.md and .nyzhi/rules.md, only AGENTS.md is loaded as the primary rule file.

Local Preferences

After the primary file, these optional files are loaded (and should be gitignored):

• NYZHI.local.md
• .nyzhi/local.md

Use these for machine-specific or personal preferences that shouldn’t be committed.

Modular Rules

Additional rules from .nyzhi/rules/*.md are loaded:

• Sorted alphabetically by filename
• Unconditional rules (no paths: frontmatter) are always appended
• Conditional rules (with paths: frontmatter) are loaded contextually

Conditional Rules

You can create rules that only apply when the agent is working on specific files:

---
paths: ["src/api/**", "*.ts"]
---

Always validate request bodies with Zod schemas.
Use consistent error response format: `{ error: { code, message } }`.

Save this as .nyzhi/rules/api-conventions.md. It will only be injected when the agent is working on files matching the patterns.

Pattern Matching

• * matches any characters within a path segment
• ** matches across directory boundaries
• Substring matching is also supported

Example Setup

A typical project might have:

project/
├── AGENTS.md              ← primary rules (committed)
├── NYZHI.local.md         ← personal preferences (gitignored)
├── .nyzhi/
│   ├── config.toml        ← project config
│   ├── rules.md           ← alternative to AGENTS.md
│   ├── local.md           ← personal preferences (gitignored)
│   ├── rules/
│   │   ├── api.md         ← conditional: API conventions
│   │   ├── testing.md     ← unconditional: test guidelines
│   │   └── security.md    ← conditional: security rules
│   └── commands/
│       └── review.md      ← custom slash command

AGENTS.md

# Project Rules

- Use TypeScript strict mode
- All functions must have JSDoc comments
- Prefer `async/await` over `.then()` chains
- Run `npm test` before committing

.nyzhi/rules/testing.md (unconditional)

# Testing Standards

- Write tests before implementation when practical
- Test edge cases, not just happy paths
- Mock external services, never call them in tests
- Use descriptive test names: `it("should reject expired tokens")`

.nyzhi/rules/api.md (conditional)

---
paths: ["src/api/**", "src/routes/**"]
---

# API Conventions

- Validate all inputs with Zod
- Return consistent error envelopes
- Use HTTP status codes correctly
- Log all 5xx errors with request context

Scaffolding with nyz init

Run nyz init to create the .nyzhi/ structure:

nyz init

This creates:

• .nyzhi/config.toml — starter config
• .nyzhi/rules.md — empty rules file
• .nyzhi/rules/ — modular rules directory
• .nyzhi/commands/ — custom commands directory
• .nyzhi/commands/review.md — example custom command
• NYZHI.local.md — local preferences (added to .gitignore)

Why Rules Matter

Rules directly affect:

• System prompt — the agent’s behavior is shaped by rules from the first turn
• Consistency — everyone on the team gets the same agent behavior
• Separation — committed rules vs personal preferences are cleanly separated
• Compatibility — works with CLAUDE.md, .cursorrules, and AGENTS.md

Next Steps

• Roles & Context Briefing — how subagents inherit context
• Configuration — project and global config
• Skills — reusable instruction packs