Contributor & AGENTS Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Contributor and AGENTS workflow defines the standard operating procedures for developers contributing to Honmoon, a polyglot monorepo comprising a Rust data plane, a TypeScript control plane, and a React-based dashboard. This workflow is anchored by AGENTS.md files distributed throughout the repository, which serve as context-specific instruction manuals for both human contributors and AI coding agents.
The project follows a strict Test-Driven Development (TDD) lifecycle, requiring a mandatory "red-green-refactor" cycle and high test coverage for all new contributions. It utilizes mise as a unified task runner to abstract the complexities of managing multiple toolchains (Rust/Cargo and JS/Bun) behind a single command interface.
Core Development Lifecycle
The Honmoon development lifecycle is built on a "test-first" philosophy. Contributors are required to write failing tests before implementing features or fixes, particularly when extending the protocol parsers or the decision engine.
Quality Gates
Before any code is committed, it must pass the project's quality gate. This ensures that the codebase remains stable and follows strict formatting and linting rules. In the Rust ecosystem, warnings are treated as errors (-D warnings).
| Step | Command | Description |
|---|---|---|
| Linting | mise run lint | Runs clippy for Rust and eslint for TypeScript. |
| Testing | mise run test | Executes the Cargo workspace tests and Bun test suite. |
| Formatting | mise run fmt | Ensures Rust code follows cargo fmt standards. |
| Full Check | mise run check | Combined gate (lint → test) that mimics the CI environment. |
Sources: wiki/getting-started/installation.md:38-54, crates/AGENTS.md:12-18
Toolchain & Command Reference
Honmoon uses mise to manage its polyglot environment. Rust is pinned via rust-toolchain.toml (version 1.85, edition 2024), while Node and Bun are managed directly by mise.
Standard Workflow Commands
The following commands are used across the repository to manage dependencies and builds:
- Initialize Environment:
mise trust && mise install - Install Dependencies:
mise run install(runscargo fetchandbun install) - Production Build:
mise run build(builds Rust workspace and Vite dashboard) - Dev Dashboard:
bun run dashboard:dev(Vite HMR server)
Sources: wiki/getting-started/installation.md:27-36, apps/dashboard/AGENTS.md:10-16
AGENTS.md Standards
Every major directory contains an AGENTS.md file that acts as a guardrail for development within that specific context. These files define the boundaries and invariants that must be preserved.
Data Plane Boundaries (crates/)
The data plane, written in Rust, is performance-critical and security-sensitive. Contributors must adhere to these rules:
- Transport-Agnostic Core:
honmoon-coreMUST NOT contain any I/O, networking, ortokiodependencies. It is pure logic. - Fail-Closed: The system must default to
denyif a rule is broken or missing. - No Payload Decryption: Extract only declared protocol facts; do not perform deep packet inspection beyond what is required by policy.
Sources: crates/AGENTS.md:32-40, AGENTS.md:50-54
Control Plane & Documentation Boundaries (wiki/, packages/)
- Sync Requirements: Changing the policy structure requires simultaneous updates to the Rust model, TypeScript types, and JSON Schema (TD-001).
- Documentation Honesty: Documentation must explicitly distinguish between implemented features and planned/scaffolded features using specific CSS status classes.
- Wiki Builds: After editing wiki pages,
bun run buildmust be executed to verify Mermaid syntax and generics. Thellms.txtfiles must be regenerated after content changes.
Sources: wiki/AGENTS.md:28-36, packages/AGENTS.md:25-30 (referenced), AGENTS.md:46-48
Git & Contribution Standards
The project enforces Conventional Commits to maintain a clean and searchable history. Each task should ideally correspond to a single commit.
Commit Types
feat: A new feature (e.g.,feat(core): add MERGE to SQL parser)fix: A bug fix (e.g.,fix(proxy): reject malformed CONNECT)test: Adding or updating testsdocs: Documentation changes inwiki/orAGENTS.mdrefactor: Code changes that neither fix bugs nor add features
Sources: wiki/onboarding/contributor-guide.md:313-322, AGENTS.md:41-44
Source Accuracy Invariant
Every architectural claim in the documentation and every Mermaid diagram MUST be followed by a citation linking to the specific source file and line numbers.
Example format: Sources: [filename.ext:start_line-end_line](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/filename.ext%3Astart_line-end_line)
Sources: wiki/AGENTS.md:21-23, wiki/onboarding/contributor-guide.md:330-335
Summary
The Contributor & AGENTS Workflow is designed to ensure that Honmoon remains a high-integrity security tool. By utilizing mise for toolchain abstraction, enforcing TDD through automated quality gates, and maintaining strict module boundaries through AGENTS.md files, the project enables both human and AI contributors to work effectively within a complex, multi-language environment while preserving critical security invariants like "fail-closed" logic and transport-agnostic core processing.