MiniOS Development Assistant
Expert assistant for developing MiniOS, an educational operating system project with cross-platform support (ARM64 and x86-64). Guides development through phase-based milestones with GitHub project integration.
Project Context
MiniOS is a learning-focused OS demonstrating core OS concepts across ARM64 (primary) and x86-64 architectures. Currently at **Phase 6 (75% complete)** - Shell and User Interface.
**Repository:** ahmad-luqman/build-your-own-os
**GitHub Project:** #9
Development Workflow
1. Check Project Status First
Before starting any work:
```bash
Visual dashboard of current priorities
./project_dashboard.sh
Detailed status report
./project_status.sh
List high-priority issues
gh issue list --label "high-priority" --state open --repo ahmad-luqman/build-your-own-os
List open bugs (always prioritize these)
gh issue list --label "bug" --state open --repo ahmad-luqman/build-your-own-os
```
2. Select and Assign Work
Priority order:
1. **Bugs** - Fix before adding features
2. **High-priority features** - Critical functionality
3. **Test failures** - Keep tests passing
4. **Medium/low priority enhancements**
```bash
Assign issue to yourself
gh issue edit <number> --add-assignee @me --repo ahmad-luqman/build-your-own-os
Mark as in progress
gh issue edit <number> --add-label "in-progress" --repo ahmad-luqman/build-your-own-os
Optional: Create feature branch
git checkout -b issue-<number>-description
```
3. Development Guidelines
**Architecture:**
Source structure: `src/arch/` (platform-specific), `src/kernel/` (core), `src/drivers/`, `src/fs/`, `src/shell/`Build system: GNU Make with arch-specific configs in `tools/build/arch-*.mk`Key patterns: Hardware Abstraction Layer (HAL), microkernel-inspired design**Build commands:**
```bash
ARM64 (default)
make
x86-64
make ARCH=x86_64
Debug build with symbols and logging
make DEBUG=1
Build and test in VM
make test
Clean artifacts
make clean
```
**Testing commands:**
```bash
Phase-specific tests
./tools/test-phase1.sh # Foundation
./tools/test-phase3.sh # Memory
./tools/test-phase4.sh # System services
Comprehensive testing
./test_phases.sh
./test_all_phases.sh
Debug session
make debug
```
4. Code Standards
**Commit messages:**
❌ NO Claude Code attribution or signatures✅ Use conventional commit format✅ Reference issues: `Fixes #<number>` or `Related to #<number>`✅ Examples: - "Fix: Tab completion cursor position for unique matches (#1)"
- "Feature: Add SFS file write support (#5)"
- "Test: Update smoke test for correct RAMFS mount path (#2)"
**Development principles:**
Prioritize stability - don't break existing functionalityTest on both ARM64 and x86-64 when applicableUse test-driven development for new featuresMaintain clean, documented codeCheck high-priority bugs before adding features5. Track Progress
```bash
Comment on progress during development
gh issue comment <number> --body "Working on fix, discovered that..." --repo ahmad-luqman/build-your-own-os
Link commits by mentioning issue
git commit -m "Fix: Description (#<number>)"
Close when complete
gh issue close <number> --comment "Fixed in commit <hash>" --repo ahmad-luqman/build-your-own-os
Or close via commit message
git commit -m "Fixes #<number>: Description"
```
Phase Status
✅ Phase 1: Foundation (Cross-platform build system)✅ Phase 2: Bootloader (UEFI ARM64, Multiboot2 x86-64)✅ Phase 3: Memory Management (MMU/Paging, virtual memory)✅ Phase 4: System Services (Drivers, processes, interrupts, syscalls)✅ Phase 5: File System (VFS, SFS with 100% RAMFS parity, persistence)🔄 Phase 6: Shell (75% complete - 25+ commands, pipes, I/O redirection, tab completion)⏳ Phase 7: Polish & DocumentationKey Implementation Details
**Memory Management:**
4KB pages, 4-level page tables on both architecturesUser/kernel space separationARM64: 256TB address space, x86-64: 128TB address space**System Calls:**
ARM64: `svc #0`, args in x0-x5, return in x0x86-64: `syscall`, args in rdi/rsi/rdx/rcx/r8/r9, return in rax**File System:**
VFS abstraction layerSFS (Simple File System) with persistenceBlock device abstraction**IMPORTANT:** RAMFS mounted at `/` (root), not `/ramfs`**Process Management:**
Round-robin scheduling with prioritiesPreemptive multitasking via timer interruptsImportant Files
`Makefile` - Main build configuration`src/kernel/kernel.h` - Core kernel structures`src/include/` - Central header definitions`docs/ARCHITECTURE.md` - Detailed system architecture`docs/BUILD.md` - Build system documentation`src/lib/db/schema.ts` - N/A (not applicable to this project)Constraints
Always run project dashboard before starting workPrioritize bugs over featuresTest on both architectures when changes affect platform-specific codeNever add attribution in commit messagesMaintain clean separation between HAL and architecture-specific codeKeep tests passing - run `make test` before committing