128 lines
5.4 KiB
Markdown
128 lines
5.4 KiB
Markdown
# RedFlag Documentation - Single Source of Truth (SSoT)
|
|
|
|
## Overview
|
|
|
|
This is the definitive documentation system for the RedFlag project. It is organized as a topical library (not a chronological journal) to provide clear, maintainable documentation for developers and users.
|
|
|
|
## Documentation Structure
|
|
|
|
The RedFlag documentation is organized into four main sections, each with a specific purpose:
|
|
|
|
```
|
|
docs/
|
|
├── redflag.md # This file - Main entry point and navigation
|
|
├── 1_ETHOS/ # The "Constitution" - Non-negotiable principles
|
|
├── 2_ARCHITECTURE/ # The "Library" - Current system state (SSoT)
|
|
├── 3_BACKLOG/ # The "Task List" - Actionable work items
|
|
└── 4_LOG/ # The "Journal" - Chronological history
|
|
```
|
|
|
|
## 1. [ETHOS/](1_ETHOS/) - The Constitution
|
|
|
|
**Purpose**: Contains the non-negotiable principles and development philosophy that guide all RedFlag development work.
|
|
|
|
**Key Files**:
|
|
- [`ETHOS.md`](1_ETHOS/ETHOS.md) - Core development principles and quality standards
|
|
|
|
**Usage**: Read this to understand:
|
|
- Why RedFlag is built the way it is
|
|
- The non-negotiable security and quality principles
|
|
- Development workflow and documentation standards
|
|
- The "contract" that all development must follow
|
|
|
|
## 2. [ARCHITECTURE/](2_ARCHITECTURE/) - The Library (SSoT)
|
|
|
|
**Purpose**: The Single Source of Truth for the current state of the RedFlag system. These files contain the authoritative technical specifications.
|
|
|
|
**Key Files**:
|
|
- [`Overview.md`](2_ARCHITECTURE/Overview.md) - Complete system architecture and components
|
|
- [`Security.md`](2_ARCHITECTURE/Security.md) - Security architecture and implementation status ⚠️ *DRAFT - Needs verification*
|
|
- [`agent/`](2_ARCHITECTURE/agent/) - Agent-specific architecture
|
|
- [`server/`](2_ARCHITECTURE/server/) - Server-specific architecture
|
|
|
|
**Usage**: Read this to understand:
|
|
- How the current system works
|
|
- Technical specifications and APIs
|
|
- Security architecture and threat model
|
|
- Component interactions and data flows
|
|
|
|
**⚠️ Important**: Some architecture files are marked as DRAFT and need code verification before being considered authoritative.
|
|
|
|
## 3. [BACKLOG/](3_BACKLOG/) - The Task List
|
|
|
|
**Purpose**: Actionable list of future work, bugs, and technical debt. This is organized by priority, not chronology.
|
|
|
|
**Usage**: Read this to understand:
|
|
- What needs to be done
|
|
- Current bugs and issues
|
|
- Technical debt that needs addressing
|
|
- Future development priorities
|
|
|
|
## 4. [LOG/](4_LOG/) - The Journal
|
|
|
|
**Purpose**: The immutable chronological history of "what happened" during development. This preserves the complete development history and decision-making process.
|
|
|
|
**Organization**:
|
|
- `_originals_archive/` - All original documentation files (backup and processing queue)
|
|
- `October_2025/` - Development sessions from October 2025
|
|
- `November_2025/` - Development sessions from November 2025
|
|
- `YYYY-MM-DD-Topic.md` - Individual session logs
|
|
|
|
**Usage**: Read this to understand:
|
|
- The complete development history
|
|
- Why certain decisions were made
|
|
- What problems were encountered and solved
|
|
- The evolution of the system over time
|
|
|
|
## How to Use This Documentation System
|
|
|
|
### For New Developers
|
|
1. **Start with ETHOS** - Read `1_ETHOS/ETHOS.md` to understand the project philosophy
|
|
2. **Read Overview** - Study `2_ARCHITECTURE/Overview.md` to understand the current system
|
|
3. **Check Backlog** - Review `3_BACKLOG/` to see what work is needed
|
|
4. **Reference LOG** - Use `4_LOG/` only when you need to understand historical context
|
|
|
|
### For Current Development
|
|
1. **ETHOS First** - Always work within the principles defined in `1_ETHOS/`
|
|
2. **Update SSoT** - Keep `2_ARCHITECTURE/` files current as the system evolves
|
|
3. **Track Work** - Add new items to `3_BACKLOG/` as you identify them
|
|
4. **Document Sessions** - Create new logs in `4_LOG/` for development sessions
|
|
|
|
### For Maintenance
|
|
1. **Regular SSoT Updates** - Keep architecture files current with actual implementation
|
|
2. **Backlog Management** - Regularly review and prioritize `3_BACKLOG/` items
|
|
3. **Log Organization** - File new development logs in appropriate date folders
|
|
4. **Verification Sessions** - Schedule focused time to verify DRAFT files against code
|
|
|
|
## The Maintenance Loop
|
|
|
|
When new documentation is created or the system changes, follow this process:
|
|
|
|
### AUDIT
|
|
- Scan for new, un-filed documentation files
|
|
- Identify what type of content they represent
|
|
|
|
### CLARIFY
|
|
- **Log**: Notes on what was just done → File in `4_LOG/` with date
|
|
- **Spec**: New design or system change → Update appropriate `2_ARCHITECTURE/` file
|
|
- **Task**: Something to be done → Extract and add to `3_BACKLOG/`
|
|
|
|
### FILE
|
|
- Move content to appropriate section
|
|
- Ensure consistency with existing documentation
|
|
- Update this entry point if needed
|
|
|
|
## Getting Started
|
|
|
|
**New to RedFlag?** Start here:
|
|
1. [ETHOS.md](1_ETHOS/ETHOS.md) - Understand our principles
|
|
2. [Overview.md](2_ARCHITECTURE/Overview.md) - Learn the system
|
|
3. [BACKLOG/](3_BACKLOG/) - See what needs doing
|
|
|
|
**Need historical context?** Dive into [4_LOG/](4_LOG/) to understand how we got here.
|
|
|
|
**Current developer?** Keep this SSoT system accurate and up-to-date. The system only works if we maintain it.
|
|
|
|
---
|
|
|
|
*This documentation system was implemented on 2025-11-12 to transform RedFlag's documentation from chronological notes into a maintainable Single Source of Truth.* |