Imported from FlexNetOS/meta (archives/yazelix-agent-cleanup-20260715/claude/worktrees/task-archbp-027-rules-authority/AGENTS.md). Install upstream with npx skills add FlexNetOS/meta --skill task-archbp-027-rules-authority. Copyright stays with the author.

Agent Guidelines

Yazelix Nova is a clean architecture track for a Yazelix-like runtime with the fewest practical lines of code and the simplest ownership model

Core Rule

The user decides scope. Do not create a feature, compatibility surface, module, or planning bead until the user has chosen that direction

Git Workflow

Work directly on main by default. Do not create a separate branch unless the user explicitly requests one or another repository instruction requires it.

Method

Use contract-driven, check-backed development, not mechanical porting from main Yazelix:

1. State the irreducible user-visible behavior in one paragraph
2. Name the current Yazelix sources of truth and decide what survives
3. Choose one owner in this repo
4. Choose the cheapest check that proves the contract
5. Implement the smallest slice that satisfies the contract
6. Avoid duplicate owners, adapters, generated fixtures, and compatibility shims
7. Record important rejected alternatives in Beads

Start with the smallest usable vertical slice and polish it before expanding

Use TDD where it fits: Rust helpers, parsers, deterministic CLI behavior, and regression fixes. Do not use classic TDD as the default for layout design, runtime integration, fork decisions, or dogfooding surfaces; write the contract and the focused check first.

Testing Discipline

Keep tests strong and few. A test should prove a contract, regression, boundary, or failure mode that matters to users or future agents.

Do not keep weak tests. If a test only repeats another check, asserts implementation trivia, or mostly preserves scaffolding, either merge its useful assertion into a stronger test or delete it.

Do not add mirror tests for straightforward literals, defaults, or configuration values whose only assertion is that the source still equals the same source-level value. If the value matters, test the user-visible behavior, boundary, or generated artifact that depends on it.

Do not add absence guards merely because code, dependencies, files, packages, settings, or features were removed. Negative checks are justified only when the absence is a real contract, such as a security, licensing, size, ownership, or known high-risk regression boundary.

Prefer one contract test with clear setup and meaningful assertions over several thin tests that make refactors harder without increasing confidence.

Current Runtime

Current chain:

yzx -> Mars -> Yazelix Zellij fork

The project interface is a Nix/Lix-compatible flake. yzx is the installed command name

After changing the flake runtime, keep the user's installed runtime current:

nix profile upgrade --refresh yazelix

Do not broaden Home Manager, layouts, config generation, plugins, pane policy, or legacy compatibility unless the user explicitly chooses that feature

Beads

Use br for all issue work. Do not edit .beads/ files directly

Serialize br write commands. Keep decisions that matter later in Beads rather than relying on chat history

LOC Discipline

Update the README LOC scorecard whenever project files change

Update CHANGELOG.md when user-visible runtime behavior, commands, keymaps, packaged tools, or runtime contracts change

Prefer deleting scope, avoiding abstractions, and reusing existing package outputs over adding local wrappers. If LOC grows, the added behavior should be visible in the scorecard and justified by the slice

Formatting rules outrank LOC pressure. For Rust, run and keep rustfmt output; do not manually compress formatted Rust just to lower the scorecard

Verification

Run the cheapest exact checks for the changed surface. For runtime flake changes, normally verify:

nix flake check
nix flake show --all-systems
nix build .#yazelix --no-link --print-build-logs
nix profile add --refresh /home/lucca/pjs/yazelix-dir/yazelix --profile <tmp>

Do not launch GUI sessions unless the user asks or reports manual dogfooding

Beads Workflow Integration

This project uses beads_rust (br) for issue tracking and beads_viewer (bv) for graph-aware triage. Issues are stored in .beads/ and tracked in git.

Using bv as an AI sidecar

bv is a graph-aware triage engine for Beads projects (.beads/beads.jsonl). Instead of parsing JSONL or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, critical path, cycles, HITS, eigenvector, k-core).

Scope boundary: bv handles what to work on (triage, priority, planning). br handles creating, modifying, and closing beads.

CRITICAL: Use ONLY --robot- flags. Bare bv launches an interactive TUI that blocks your session.*

The Workflow: Start With Triage

bv --robot-triage is your single entry point. It returns everything you need in one call:

• quick_ref: at-a-glance counts + top 3 picks
• recommendations: ranked actionable items with scores, reasons, unblock info
• quick_wins: low-effort high-impact items
• blockers_to_clear: items that unblock the most downstream work
• project_health: status/type/priority distributions, graph metrics
• commands: copy-paste shell commands for next steps

bv --robot-triage        # THE MEGA-COMMAND: start here
bv --robot-next          # Minimal: just the single top pick + claim command

# Token-optimized output (TOON) for lower LLM context usage:
bv --robot-triage --format toon

Before claiming, verify current state with br show <id> --json or br ready --json. recommendations can include graph-important blocked or assigned work; only quick_ref.top_picks and non-empty claim_command fields represent claimable work.

Other bv Commands

Scoping & Filtering

bv --robot-plan --label backend              # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30          # Historical point-in-time
bv --recipe actionable --robot-plan          # Pre-filter: ready to work (no blockers)
bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank scores

br Commands for Issue Management

br ready              # Show issues ready to work (no blockers)
br list --status=open # All open issues
br show <id>          # Full issue details with dependencies
br create --title="..." --type=task --priority=2
br update <id> --status=in_progress
br close <id> --reason="Completed"
br close <id1> <id2>  # Close multiple issues at once
br sync --flush-only  # Export DB to JSONL

Workflow Pattern

1. Triage: Run bv --robot-triage to find the highest-impact actionable work
2. Claim: Use br update <id> --status=in_progress
3. Work: Implement the task
4. Complete: Use br close <id>
5. Sync: Always run br sync --flush-only at session end

Key Concepts

• Dependencies: Issues can block other issues. br ready shows only unblocked work.
• Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
• Types: task, bug, feature, epic, chore, docs, question
• Blocking: br dep add <issue> <depends-on> to add dependencies

Session Protocol

git status              # Check what changed
git add <files>         # Stage code changes
br sync --flush-only    # Export beads changes to JSONL
git commit -m "..."     # Commit everything
git push                # Push to remote