Redflag/docs/redflag.md

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/ - The Constitution

Purpose: Contains the non-negotiable principles and development philosophy that guide all RedFlag development work.

Key Files:

• 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/ - 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 - Complete system architecture and components
• Security.md - Security architecture and implementation status ⚠️ DRAFT - Needs verification
• agent/ - Agent-specific 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/ - 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/ - 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 - Understand our principles
2. Overview.md - Learn the system
3. BACKLOG/ - See what needs doing

Need historical context? Dive into 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.