chanora/AGENTS.md

AGENTS.md — Chanora Project Conventions

Project Overview

Chanora is a cross-platform voice client (Flutter + Rust) targeting TeamSpeak-compatible servers. The project follows ASPICE engineering processes with full traceability from system requirements through verification.

Repository Structure

chanora/                          ← Code repo (this one)
├── docs/ → chanoraapp/docs       ← Git submodule: ASPICE docs, Docusaurus doc site
├── dev-docs/                     ← Local-only development docs
│   ├── superpowers/              ← AI agent specs and plans
│   │   ├── specs/                ← Feature/design specs (active)
│   │   └── plans/                ← Implementation plans (active)
│   │       └── _archived/        ← Completed plans
│   ├── offline-knowledge/        ← Doc maintenance tools, link coverage
│   ├── implementation-status-*   ← Code state snapshots
│   └── release/ios-build.md      ← Operational build instructions
├── apps/chanora_flutter/         ← Flutter application
├── core/chanora_core/            ← Rust core API + orchestration
├── crates/                       ← Rust crates (protocol, audio, state, etc.)
└── dev-docs/impl-mapping.md      ← SAD component → source file mapping

Documentation Two-Repo Model

docs/ is a git submodule pointing to the chanoraapp/docs repository. It serves a Docusaurus doc site with ASPICE traceability. It is NOT a local directory you can freely create files in.

What lives where

Content	Location	Reason
SysRS, SysDes, SRS, SAD, SDD	docs/ (submodule)	ASPICE baselines, served on doc site
Verification plans (SWE.4/5/6, SYS.4)	docs/ (submodule)	ASPICE verification evidence
Governance, traceability, decision register	docs/ (submodule)	ASPICE governance
Security, privacy, legal	docs/ (submodule)	Stakeholder-facing
UI/UX guidelines, i18n architecture	docs/ (submodule)	Design references
Feature specs and implementation plans	dev-docs/superpowers/	Code-coupled, agent working files
Link coverage, doc quality analysis	dev-docs/offline-knowledge/	Maintenance tools
Implementation status snapshots	dev-docs/	Code state tracking
Source file path references	dev-docs/impl-mapping.md	Developer convenience, not ASPICE

Rules for agents

1. Never create or edit files in docs/ without understanding it's a submodule. Changes there require committing in the chanoraapp/docs repo first, then updating the submodule pointer in this repo.

2. ASPICE documents do not contain code file paths. ASPICE traces requirement IDs (e.g., SysRS-233, SRS-045, SDD-MOD-009), not source file paths. If you need to map a component to its source, use or update dev-docs/impl-mapping.md.

3. Specs and plans go in dev-docs/superpowers/. Follow the naming convention: YYYY-MM-DD-<topic>-design.md for specs, YYYY-MM-DD-<topic>.md for plans.

4. Completed plans move to _archived/. Once a plan is fully implemented and verified, move it to dev-docs/superpowers/plans/_archived/.

5. Doc site uses Docusaurus. The chanoraapp/docs repo uses Docusaurus 3.10 (Meta-maintained). Do not add MkDocs, mdBook, or other doc site generators.

ASPICE Traceability Chain

SysRS → SysDes → SRS → SAD (SWE.2) → SDD (SWE.3) → Verification
                                           ↓              ↓
                                       SWE.4 (unit)   SWE.4/5/6/SYS.4

• Requirement IDs are the traceability mechanism, not file paths.
• Every downstream document must reference upstream IDs it traces from.
• Verification plans map to their upstream design/requirements level:
  • SYS.4 ← SysDes, SysRS
  • SWE.5 ← SAD (SWE.2)
  • SWE.4 ← SDD (SWE.3)
  • SWE.6 ← SRS
• Requirement IDs should be added to doc front matter tags: for traceability browsing.

Code Architecture

Component	Location	Responsibility
Flutter app shell	apps/chanora_flutter/	UI, Material 3, navigation, localization
Rust core	core/chanora_core/	Session orchestration, bridge events
Protocol adapter	crates/chanora_protocol/	TeamSpeak protocol via tsclientlib
State sync	crates/chanora_state/	Snapshots, deltas, reducers
Audio subsystem	crates/chanora_audio/	Capture, DSP, Opus, PTT
Storage	crates/chanora_storage/	Bookmarks, identity, encryption
Diagnostics	crates/chanora_diagnostics/	Redaction, logs, export
Resolver	crates/chanora_resolver/	SRV/TSDNS/DNS resolution
Prefetch	crates/chanora_prefetch/	Resolution warming, TTL cache
Bridge	crates/chanora_bridge/	Flutter/Rust typed DTO boundary
Cache	crates/chanora_cache/	Avatar/icon blob cache

Coding Conventions

• Rust: Follow workspace Cargo.toml structure. Run cargo check, cargo clippy, cargo test before committing.
• Flutter: Run flutter analyze, flutter test before committing.
• No code comments unless explicitly requested.
• Git commits: Follow convention in docs/governance/git-commit-message-convention.md (accessible via submodule).
• Bridge boundary: Flutter must not directly depend on protocol-library internals. All cross-boundary communication goes through chanora_bridge typed DTOs.

Verification Commands

cargo check && cargo clippy && cargo test
cd apps/chanora_flutter && flutter analyze && flutter test

Important References

• Traceability matrix: docs/governance/traceability-matrix.md
• Decision register: docs/governance/product-decision-register.md
• Security guidelines: docs/security/security-privacy-legal-guideline.md
• Release readiness: docs/release/release-readiness-go-nogo-record.md
• Doc site repo: chanoraapp/docs (Docusaurus)
• Doc site local preview: cd docs && npm run start