1  # Dawn Agents
 2  
 3  This file documents the specialized agents and workflows used in the Dawn project.
 4  
 5  ## Specialized Agents
 6  
 7  - **Generalist**: Handles broad tasks across the codebase.
 8  - **Codebase Investigator**: Specialized in deep analysis and dependency mapping.
 9  - **CLI Help**: Expert on Gemini CLI features and configuration.
10  
11  ## Workflows
12  
13  ### 1. Research
14  Systematically map the codebase and validate assumptions.
15  
16  ### 2. Strategy
17  Formulate a grounded plan based on research.
18  
19  ### 3. Execution
20  Iterative Plan -> Act -> Validate cycle for each sub-task.
21  
22  ## Quality Gates
23  The project uses `just` to enforce quality gates as defined in `GEMINI.md`.
24  
25  ## Technical Stack (Dark Factory)
26  
27  The Dawn project fuses the following tools for a "Dark Factory" operation:
28  
29  - **Nix Flake & Flakebox**: Provides a 100% reproducible development environment. All tools are pinned and managed via `flake.nix`.
30  - **Justfile**: The command proxy for all project operations. Direct use of `cargo` or `nix` (except `develop`) is discouraged.
31  - **Cargo Workspace**: Manages modular crates with dependency sovereignty.
32  - **Sovereign Dependencies**: All external dependencies are defined in the root `Cargo.toml` under `[workspace.dependencies]`.
33  - **Sccache**: Used for rapid recompilation. The cache is configured in `$HOME/.cache/sccache` with a large capacity.
34  - **Wild Linker**: Used on Linux targets for faster linking.
35  - **Bevy CLI**: Primary tool for Bevy-specific builds and lints, especially for Web (WASM).
36  - **Trunk**: Alternative/supporting tool for WASM assets.
37  - **Cargo NDK**: Used for Android compilation.
38  - **Cross-rs**: Used for cross-compiling to Windows and other platforms.
39  
40  ## Operational Procedures
41  
42  1.  **Enter Environment**: Use `nix develop` or `direnv`.
43  2.  **Execute Task**: Follow the Research -> Strategy -> Execution cycle.
44  3.  **Verify**: Run `just quality` or `just full-quality`.
45  4.  **Report**: Save a report in `reports/` for every task completion.
46  5.  **Commit**: Use the `autonomous:` prefix with diff stats.
47  6.  **Ship**: Use `just ship` to verify, commit, and sync.
48  
49  ## Large References Management
50  
51  To maintain a minimalist repository while providing agents with necessary external knowledge, the project employs the following strategy:
52  
53  - **External Refs**: Large projects and specifications are kept in `.config/refs`.
54  - **Submodule Pattern**: These references are maintained as Git submodules where possible.
55  - **Agent Awareness**: Agents should look in `.config/refs` for specialized specifications (e.g., `secretspec`).