refactor: restructure docs as submodule, add dev-docs/ and AGENTS.md

- Move ASPICE docs to chanoraapp/docs submodule at docs/ - Move development docs to dev-docs/ (superpowers, offline-knowledge, impl-mapping) - Add AGENTS.md with project conventions for AI agents - Add impl-mapping.md (SAD component → source file mapping) - Archive completed plans to dev-docs/superpowers/plans/_archived/ - Remove AGENTS.md from .gitignore (now tracked)
2026-06-13 03:32:33 +09:00
parent 5765e9cf6f
commit bba6273af7
98 changed files with 2113 additions and 30548 deletions
@@ -0,0 +1,111 @@
+# 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
+
+```text
+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
+
+```bash
+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`