Loong Agent Guide

This document is intentionally mirrored in CLAUDE.md and AGENTS.md.

This file is the map — keep it short (~100 lines). Deeper repo-native context lives in docs/, while the public reader-facing docs surface lives in site/.

1. Start Here

• Repository Docs Map — audience routing for site/ vs docs/
• Core Beliefs — kernel and engineering principles
• Layered Kernel Design — layered model and boundary rules
• Roadmap — stage-based milestones and acceptance criteria
• Reliability — invariants and operating expectations
• Code Standards — maintainability, test layout, and review checks
• Product specs and implementation plans now live in eastreams/knowledge-base (see docs/README.md for routing)
• Contributing Guide — contributor workflow and recipes

2. Architecture Contract

The workspace currently has 13 crates across two connected families:

additive spine
loong-core (leaf)
├── loong-plugin-sdk → loong-core
├── loong-runtime → loong-core
├── loong-app-protocol → loong-runtime
└── loong-cli → loong-app-protocol

governed runtime
contracts (leaf)
├── kernel → contracts, loong-plugin-sdk
├── protocol (independent leaf)
├── bridge-runtime → contracts, kernel, protocol
├── app → contracts, kernel
├── spec → contracts, kernel, protocol, bridge-runtime
├── bench → kernel, spec
└── daemon (`loong`) → app, loong-app-protocol, bench, bridge-runtime, contracts, kernel, protocol, spec

Non-negotiable: no dependency cycles. See Core Beliefs. Current tracked deviations: none. loong-cli remains transitional; the shipped product entrypoint is still the loong binary in crates/daemon.

3. Commands

Taskfile.yml provides optional convenience wrappers through the task CLI. If task is unavailable, run the underlying cargo and scripts/* commands directly.

• Format check: ./scripts/cargo-local-toolchain.sh fmt --all -- --check
• Strict lint: ./scripts/cargo-local-toolchain.sh clippy --workspace --all-targets --all-features -- -D warnings
• Architecture check: ./scripts/check_architecture_boundaries.sh or task check:architecture
• Convention check: task check:conventions (optional wrapper; requires Go + convention-engineering skill)
• Test all features: ./scripts/cargo-local-toolchain.sh test --workspace --all-features
• Canonical verify: task verify (optional wrapper around repo verification steps)
• Extended verify: task verify:full (optional wrapper around the extended local gate)

4. Non-Negotiable Rules

• Kernel contracts are backward-compatible. No breaking changes without documented decision.
• All execution paths route through kernel capability/policy/audit. No shadow paths.
• Strict lint and all-feature tests pass at every commit.
• Never commit credentials, tokens, or private endpoints.
• Keep CLAUDE.md and AGENTS.md mirrored in the same change.
• Before every commit, run CI-parity checks. Any manual edit after fmt must be re-checked.
• Every released version must map to docs/releases/vX.Y.Z.md with process log and detail links.
• Local agent debug context for a release should be recorded in .docs/releases/vX.Y.Z-debug.md.
• Public-repo issues, PRs, and public-doc wording should stay Loong-centric; keep detailed external project comparisons in eastreams/knowledge-base unless naming an external project is strictly necessary.

5. Verification Gates

CI enforces:

• ./scripts/cargo-local-toolchain.sh fmt --all -- --check
• ./scripts/cargo-local-toolchain.sh clippy --workspace --all-targets --all-features -- -D warnings
• ./scripts/cargo-local-toolchain.sh test --workspace
• ./scripts/cargo-local-toolchain.sh test --workspace --all-features

6. Pre-Commit Hook

cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Runs CI-parity cargo checks before each commit. Use task verify when the task CLI is installed. Otherwise run the underlying scripts/cargo-local-toolchain.sh and scripts/* verification commands directly.

7. Where to Look Next