Files

Fimeg 484a7f77ce Add docs and project files - force for Culurien

2026-03-28 20:46:24 -04:00

15 KiB

Raw Permalink Blame History

RedFlag Development Workflow Guide

Overview

This guide explains the development workflow and documentation methodology for RedFlag. The project has evolved from a monolithic development log to organized day-based documentation with clear separation of concerns.

Documentation Structure

Day-Based Documentation

Development sessions are organized into individual day files in the docs/days/ directory:

docs/days/
├── 2025-10-12-Day1-Foundations.md
├── 2025-10-12-Day2-Docker-Scanner.md
├── 2025-10-13-Day3-Local-CLI.md
├── 2025-10-14-Day4-Database-Event-Sourcing.md
├── 2025-10-15-Day5-JWT-Docker-API.md
├── 2025-10-15-Day6-UI-Polish.md
├── 2025-10-16-Day7-Update-Installation.md
├── 2025-10-16-Day8-Dependency-Installation.md
├── 2025-10-17-Day9-Refresh-Token-Auth.md
└── 2025-10-17-Day9-Windows-Agent.md

Core Documentation Files

README.md - Project overview and quick start
PROJECT_STATUS.md - Current project status, known issues, and roadmap
ARCHITECTURE.md - Technical architecture documentation
DEVELOPMENT_WORKFLOW.md - This file - development methodology
docs/days/README.md - Overview of day-based documentation

Development Session Workflow

Before Starting a Session

Review Current Status: Check PROJECT_STATUS.md for current priorities
Read Previous Day: Review the most recent day file to understand context
Set Clear Goals: Define specific objectives for the session
Update Todo List: Use TodoWrite tool to track session progress

During Development

Code Implementation: Write code following the existing patterns
Regular Documentation: Take notes as you work (don't wait until end)
Track Progress: Update TodoWrite as tasks are completed
Testing: Verify functionality works as expected

After Session Completion

Create Day File: Create a new day file in docs/days/ with format:
```
YYYY-MM-DayN-Session-Topic.md
```
Document Progress: Include:
- Session time (start/end)
- Goals vs achievements
- Technical implementation details
- Code statistics
- Files modified/created
- Impact assessment
- Next session priorities
Update Status Files:
- Update PROJECT_STATUS.md with new capabilities
- Update README.md if major features were added
- Update any relevant architecture documentation
Clean Up:
- Review and organize todo list
- Remove completed tasks
- Add new tasks identified during session

File Naming Conventions

Day Files

Format: YYYY-MM-DD-DayN-Topic.md
Examples: 2025-10-15-Day5-JWT-Docker-API.md
Location: docs/days/

Content Structure

Each day file should follow this structure:

# YYYY-MM-DD (Day N) - SESSION TOPIC

**Time Started**: ~HH:MM UTC
**Time Completed**: ~HH:MM UTC
**Goals**: Clear objectives for the session

## Progress Summary

✅ **Major Achievement 1**
- Details of what was accomplished
- Technical implementation notes
- Result/impact

✅ **Major Achievement 2**
- ...

## Technical Implementation Details

### Key Components
- Architecture decisions
- Code patterns used
- Integration points

### Code Statistics
- Lines of code added/modified
- Files created/updated
- New functionality implemented

## Files Modified/Created
- ✅ file_path (description of changes)
- ✅ file_path (description of changes)

## Testing Verification
- ✅ What was tested and confirmed working
- ✅ End-to-end workflow verification

## Impact Assessment
- **MAJOR IMPACT**: Critical improvements
- **USER VALUE**: Benefits to users
- **STRATEGIC VALUE**: Long-term benefits

## Next Session Priorities
1. Priority 1 (description)
2. Priority 2 (description)

Documentation Principles

Be Specific and Technical

Include exact file paths with line numbers when relevant
Provide code snippets for key implementations
Document the "why" behind technical decisions
Include actual error messages and solutions

Track Metrics

Lines of code added/modified
Files created/updated
Performance improvements
User experience enhancements

Focus on Outcomes

What problems were solved
What new capabilities were added
How the system improved
What user value was created

Todo Management

TodoWrite Tool Usage

The TodoWrite tool helps track progress within sessions:

// Example usage
TodoWrite({
  todos: [
    {
      content: "Implement feature X",
      status: "in_progress",
      activeForm: "Working on feature X implementation"
    },
    {
      content: "Write tests for feature X",
      status: "pending",
      activeForm: "Will write tests after implementation"
    }
  ]
})

Todo States

pending: Not started yet
in_progress: Currently being worked on
completed: Finished successfully

Session Planning

Types of Sessions

Feature Development: Implementing new functionality
Bug Fixing: Resolving issues and problems
Architecture: Major system design changes
Documentation: Improving project documentation
Testing: Comprehensive testing and validation
Refactoring: Code quality improvements

Session Sizing

Short Sessions (1-2 hours): Focused bug fixes, small features
Medium Sessions (3-4 hours): Major feature implementation
Long Sessions (6+ hours): Architecture changes, complex features

Priority Setting

Use the PROJECT_STATUS.md file to guide session priorities:

Critical Issues: Blockers that prevent core functionality
User Experience: Improvements that affect user satisfaction
Security: Vulnerabilities and security hardening
Performance: Optimization and scalability
Features: New capabilities and functionality

Code Review Process

Self-Review Checklist

Before considering a session complete:

Functionality: Does the code work as intended?
Testing: Have you tested the implementation?
Documentation: Is the change properly documented?
Integration: Does it work with existing functionality?
Error Handling: Are edge cases properly handled?
Security: Does it introduce any security issues?

Documentation Review

Ensure all documentation is updated:

Day file created with complete session details
PROJECT_STATUS.md updated if needed
README.md updated for major features
Code comments added for complex logic
API documentation updated if endpoints changed

Communication Guidelines

Session Summaries

Each day file should serve as a complete session summary that:

Allows someone to understand what was accomplished
Provides context for the next development session
Documents technical decisions and their rationale
Includes measurable outcomes and impacts

Progress Tracking

Use the TodoWrite tool to:

Track progress within active sessions
Maintain context across multiple sessions
Provide visibility into development status
Hand off work between sessions smoothly

Tools and Commands

Project Structure Commands

# View project structure (excluding common build artifacts)
tree -a -I 'node_modules|dist|target|.git|*.log' --dirsfirst

# Alternative: Simple view without hidden files
tree -I 'node_modules|dist|target|.git|*.log'

# Show current git status
git status

# Show recent commits
git log --oneline -10

# Show file changes in working directory
git diff --stat

Current Project Structure

The RedFlag project has the following structure (43 directories, 170 files):

.
├── aggregator-agent/           # Cross-platform Go agent
│   ├── cmd/agent/              # Agent entry point
│   ├── internal/               # Core agent functionality
│   │   ├── cache/              # Local caching system
│   │   ├── client/             # Server communication
│   │   ├── config/             # Configuration management
│   │   ├── display/            # Terminal output formatting
│   │   ├── installer/          # Package installers (APT, DNF, Docker, Windows)
│   │   ├── scanner/            # Package scanners (APT, DNF, Docker, Windows, Winget)
│   │   └── system/             # System information collection
│   └── pkg/windowsupdate/      # Windows Update API bindings
├── aggregator-server/          # Go backend server
│   ├── cmd/server/             # Server entry point
│   ├── internal/
│   │   ├── api/handlers/       # REST API handlers
│   │   ├── database/           # Database layer (migrations, queries)
│   │   ├── models/             # Data models
│   │   └── services/           # Business logic services
├── aggregator-web/             # React TypeScript frontend
│   └── src/
│       ├── components/         # React components
│       ├── hooks/              # Custom React hooks
│       ├── pages/              # Page components
│       └── lib/                # Utilities and API clients
├── docs/
│   ├── days/                   # Day-by-day development logs
│   └── *.md                    # Technical documentation
└── Screenshots/                # Project screenshots and demos

Development Commands

# Start all services
docker-compose up -d

# Build agent
cd aggregator-agent && go build -o aggregator-agent ./cmd/agent

# Build server
cd aggregator-server && go build -o redflag-server ./cmd/server

# Build web frontend
cd aggregator-web && npm run build

# Run tests
go test ./...

Quality Standards

Code Quality

Follow Go best practices for backend code
Use TypeScript properly for frontend code
Include proper error handling
Add meaningful comments for complex logic
Maintain consistent formatting and style

Documentation Quality

Be accurate and specific
Include relevant technical details
Focus on outcomes and impact
Maintain consistent structure
Update related documentation files

Testing Quality

Test core functionality
Verify error handling
Check integration points
Validate user workflows
Document test results

🔄 Maintaining the Documentation System

Critical: Self-Sustaining Documentation

EVERY SESSION MUST MAINTAIN THIS DOCUMENTATION PATTERN - This is not optional:

ALWAYS Create Day Files: No matter how small the session, create a day file
ALWAYS Update Status Files: PROJECT_STATUS.md must reflect current reality
ALWAYS Track Technical Debt: Update deferred features and known issues
ALWAYS Use TodoWrite: Maintain session progress visibility

Documentation System Maintenance

Required Session End Tasks (NON-NEGOTIABLE):

# 1. Create day file (MANDATORY)
Format: docs/days/YYYY-MM-DD-DayN-Topic.md

# 2. Update status files (MANDATORY)
- Update PROJECT_STATUS.md with new capabilities
- Add new technical debt items to "Known Issues"
- Update "Current Status" section with latest achievements
- Update "Next Session Priorities" based on session outcomes

# 3. Update day index (MANDATORY)
- Add new day file to docs/days/README.md
- Update claude.md with latest session summary

Technical Debt Tracking Requirements

Every session must identify and document:

New Technical Debt: What shortcuts were taken?
Deferred Features: What was postponed and why?
Known Issues: What problems were discovered but not fixed?
Architecture Decisions: What technical choices need future review?

Add these to PROJECT_STATUS.md in appropriate sections:

## 🚨 Known Issues

### Critical (Must Fix Before Production)
- Add new critical issues discovered

### Medium Priority
- Add new medium priority items

### Low Priority
- Add new low priority technical debt

## 🔄 Deferred Features Analysis
- Update with any new deferred features identified

Pattern Discipline: Why This Matters

Without strict adherence, the system collapses:

Context Loss: Future sessions won't understand current state
Technical Debt Accumulation: Deferred items become forgotten
Priority Confusion: No clear sense of what matters most
Knowledge Fragmentation: Important details lost in conversation

With strict adherence:

Sustainable Development: Each session builds on clear context
Technical Debt Visibility: Always know what needs attention
Priority Clarity: Clear sense of most important work
Knowledge Preservation: Complete technical history maintained

Self-Enforcement Mechanisms

The documentation system includes several self-enforcement patterns:

1. TodoWrite Discipline

// Start each session with todos
TodoWrite({
  todos: [
    {content: "Review PROJECT_STATUS.md", status: "pending"},
    {content: "Read previous day file", status: "pending"},
    {content: "Implement session goals", status: "pending"},
    {content: "Create day file", status: "pending"},
    {content: "Update PROJECT_STATUS.md", status: "pending"}
  ]
})

2. Status File Validation

Before considering a session complete, verify:

PROJECT_STATUS.md reflects new capabilities
All new technical debt is documented
Known issues section is updated
Next session priorities are clear

3. Day File Quality Checklist

Each day file must include:

Session timing (start/end)
Clear goals and achievements
Technical implementation details
Files modified/created with specifics
Code statistics and impact assessment
Next session priorities

Pattern Reinforcement

When starting any session:

Claude should automatically: "First, let me review the current project status by reading PROJECT_STATUS.md and the most recent day file to understand our context."
User should see: Clear reminder of documentation responsibilities
Session should end: With explicit confirmation that documentation is complete

Anti-Patterns to Avoid

❌ "I'll document it later" - Never works, details are lost ❌ "This session was too small to document" - All sessions matter ❌ "The technical debt isn't important enough to track" - It will become important ❌ "I'll remember this decision" - You won't, document it

Positive Patterns to Follow

✅ Document as you go - Take notes during implementation ✅ End each session with documentation - Make it part of completion criteria ✅ Track all decisions - Even small choices have future impact ✅ Maintain technical debt visibility - Hidden debt becomes project risk

Continuous Improvement

Learning from Sessions

After each session, consider:

What went well?
What could be improved?
Were goals realistic?
Was time used effectively?
Are documentation processes working?
Did I maintain the pattern correctly?

Process Refinement

Regularly review and improve:

Documentation structure and clarity
Development workflow efficiency
Goal-setting and planning accuracy
Communication and collaboration methods
Quality assurance processes
Pattern adherence discipline

This workflow ensures consistent, high-quality development while maintaining comprehensive documentation that serves both current development needs and future project understanding. The pattern only works if consistently maintained.

15 KiB Raw Permalink Blame History