README

Templates for the GoGrab Space

Phase Documentation Template

🤖 AI Agents: Follow this template when creating new phase documentation for any project.

🤖 Quick Start: Automated Creation

The intelligent way - use our automation script:

cd /docs/english/Templates/phases-template/
./create-phase.sh <phase-number> <project-path> "<phase-name>"

# Examples:
./create-phase.sh 10 GoGrab-Space/user-journey "Production Launch"
./create-phase.sh 2 GoGrab-Space/universe-restructure "Integration Complete"

What it does automatically:

✅ Creates complete folder structure
✅ Creates context/ subdirectory
✅ Copies and renames all templates
✅ Fills in dates, times, and phase numbers
✅ Checks for previous phase context
✅ Runs documentation scan

Time: ~30 seconds vs 20+ minutes manually!

📋 Template Structure

Every phase must include these files:

phase-X/
├── index.mdc                     # Phase overview with frontmatter
├── PHASE-X-COMPLETE-PLAN.md      # Comprehensive implementation plan
├── achievements.md                # Feature completion tracking
├── progress.md                    # Daily progress notes
├── next-steps.md                  # Immediate action items
└── context/                       # Context folder (IMPORTANT!)
    ├── [Previous session reports]
    ├── [Integration status docs]
    ├── [Achievement summaries]
    └── [Historical context files]

📁 Context Folder (Critical for AI Agents)

Purpose: The context/ folder contains historical documentation that helps AI agents understand previous work.

What Goes Here:

Session completion reports
Integration status documents
Achievement summaries from previous sessions
Breakthrough implementation notes
Honest status assessments
Realistic roadmaps

Why It Matters: AI agents should ALWAYS read the context folder FIRST before continuing work on a phase. This ensures continuity and prevents repeating work or missing important context.

Example:

phase-1/
└── context/
    ├── COMPLETE-INTEGRATION-STATUS-NOV-9-2025.md
    ├── FINAL-SESSION-REPORT-NOV-9-2025.md
    ├── HONEST-STATUS-ASSESSMENT-NOV-9-2025.md
    └── REALISTIC-ROADMAP-TO-100-PERCENT.md

🎯 When to Create a New Phase

Create a new phase when:

Major milestone reached - Previous phase has achieved its core goals
Scope shift - Project requires new focus area or approach
Complexity threshold - Current phase exceeds ~50 hours or becomes too large
Natural breakpoint - Logical separation point in project timeline

Rule: Each phase should be focused, achievable, and measurable.

📝 File-by-File Instructions

1. `index.mdc` - Phase Overview

Purpose: High-level summary and navigation hub for the phase

Frontmatter Requirements:

---
title: Phase X - [Phase Name]
description: [Brief one-sentence description]
icon: 🎯 # Choose appropriate emoji
created: [Month Day, Year]
updated: [Month Day, Year] [Time]
status: 🎯 [ACTIVE/COMPLETE/PLANNED]
purpose: [What this phase accomplishes]
order: 1
tags: [phase-X, tag1, tag2, tag3]
---

Content Structure:

Title & Timeline - Phase name, start date, estimated duration
Phase Overview - Core goals (3-5 bullet points)
Documentation - Links to all phase files
Current State - What's working vs. what needs work
Focus Areas - Main implementation areas with time estimates
Success Criteria - Clear completion checklist
The Vision - What's possible after phase completion

Template: See index.mdc.template

2. `PHASE-X-COMPLETE-PLAN.md` - Implementation Plan

Purpose: Comprehensive technical roadmap with code examples

Frontmatter Requirements:

---
title: Phase X Complete Implementation Plan
description: [Comprehensive plan description]
icon: 🎯
created: [Month Day, Year]
updated: [Month Day, Year] [Time]
status: 🎯 IMPLEMENTATION PLAN
purpose: [Systematic roadmap for achieving X]
order: 2
tags: [phase-X, plan, implementation, relevant-tags]
---

Content Structure:

Timeline & Goal - Overall time estimate and main objective
Gap Analysis - What's complete vs. what's remaining
Detailed Implementation - Day-by-day breakdown with:
- Technical requirements
- Code examples
- File locations
- Implementation steps
Acceptance Criteria - Checklist for each major area
Critical Fixes - Detailed solutions for known issues
Implementation Timeline - Table with days/hours/deliverables
The Vision - End-user experience after completion

Template: See PHASE-X-COMPLETE-PLAN.md.template

3. `achievements.md` - Feature Completion Tracking

Purpose: Record of completed milestones and features

Frontmatter Requirements:

---
title: Phase X Achievements
description: Record of completed features and milestones
icon: 🏆
created: [Month Day, Year]
updated: [Month Day, Year] [Time]
status: 📝 TRACKING
purpose: Track achievements during phase
order: 4
tags: [phase-X, achievements, milestones]
---

Content Structure:

Phase Info - Start date and goal
Major Milestones - 3-5 key milestones with:
- Target dates
- Feature lists (checkboxes)
- Impact statements
Carried Forward - Completed items from previous phase
Progress by Category - Visual progress bars
Achievement Log - Chronological completion list

Template: See achievements.md.template

Update Frequency: After each significant feature completion

4. `progress.md` - Daily Progress Notes

Purpose: Detailed day-by-day tracking of work and decisions

Frontmatter Requirements:

---
title: Phase X Progress Notes
description: Daily progress tracking
icon: 📝
created: [Month Day, Year]
updated: [Month Day, Year] [Time]
status: 🚀 IN PROGRESS
purpose: Track daily progress and decisions
order: 3
tags: [phase-X, progress, tracking]
---

Content Structure:

Overall Progress - Visual progress bars for all areas
Daily Progress - Entries for each work session:
- Date & time
- Activities completed
- Decisions made
- Blockers encountered
- Next steps
- Time spent
Milestones - Current status of major milestones
Current Focus - What's happening now

Template: See progress.md.template

Update Frequency: After every work session (multiple times per day)

5. `next-steps.md` - Immediate Action Items

Purpose: Clear, actionable next steps prioritized by urgency

Frontmatter Requirements:

---
title: Phase X Next Steps
description: Immediate actions for completing phase
icon: ⏭️
created: [Month Day, Year]
updated: [Month Day, Year] [Time]
status: 🎯 ACTION ITEMS
purpose: Clear next actions for Phase X
order: 5
tags: [phase-X, next-steps, actions]
---

Content Structure:

Immediate Actions - Top 3-5 actions with:
- Priority level (🔴 CRITICAL, 🟡 HIGH, 🟢 MEDIUM)
- Time estimate
- Problem statement
- Solution approach
- Test criteria
This Week Plan - Day-by-day breakdown
Success Criteria - When phase is complete

Template: See next-steps.md.template

Update Frequency: Daily or after completing action items

🎨 Naming Conventions

File Names

✅ DO: PHASE-9-COMPLETE-PLAN.md (all caps, hyphens)
✅ DO: index.mdc (lowercase, .mdc extension)
✅ DO: achievements.md (lowercase, descriptive)
❌ DON'T: Phase-9-Plan.md (inconsistent capitalization)
❌ DON'T: next_steps.md (use hyphens, not underscores)

Progress Notes Files

📝 In-Progress Files: PROGRESS_NOTE_NOV_10.md (ALL CAPS with underscores)
✅ Completed Files: final-session-notes.md (kebab-case when complete)

🔄 Workflow for AI Agents

Starting a New Phase

Read Context Folder FIRST ⚠️ CRITICAL
- Navigate to previous phase's context/ folder
- Read all session reports and status documents
- Understand what was achieved
- Identify what's carried forward
- Note any blockers or decisions made
Assess Previous Phase
- Review achievements from context
- Calculate completion percentage
- Identify gaps or remaining work

Create Phase Structure

mkdir phase-X
cd phase-X
mkdir context  # Create context folder immediately

Generate All 5 Files
- Start with index.mdc (overview)
- Create PHASE-X-COMPLETE-PLAN.md (detailed plan)
- Initialize achievements.md (empty log)
- Initialize progress.md (Day 0 entry)
- Create next-steps.md (immediate actions)
Link Documentation
- Add phase to parent index
- Link to previous phase
- Reference relevant docs

During Phase Execution

Update progress.md after every work session
Update achievements.md when milestones complete
Update next-steps.md daily
Update index.mdc when status changes
Keep COMPLETE-PLAN.md as reference (minor updates only)
Add to context/ folder when major sessions complete (final reports, status docs)

Completing a Phase

Final Updates
- Mark all achievements as complete
- Update all status fields to "✅ COMPLETE"
- Add "Last Updated" timestamps
- Create completion summary
Archive to Context Folder
- Move final session reports to context/
- Add completion summary to context/
- Add any major status documents to context/
- This helps future AI agents understand what was accomplished
Create Next Phase
- Review what's left
- Read current phase's context folder
- Plan next focus areas
- Generate new phase structure with context folder
Run Documentation Scan
```
yarn docs:scan
```

📊 Progress Tracking Guidelines

Visual Progress Bars

Use this format for progress tracking:

Feature Name         [████████░░] 80% (8/10 hours)

Status Emojis

🎯 PLANNED - Not started yet
🚀 IN PROGRESS - Currently working
✅ COMPLETE - Finished and verified
⏳ PENDING - Waiting on something
🔴 BLOCKED - Cannot proceed
📝 TRACKING - Ongoing documentation

Priority Indicators

🔴 CRITICAL - Blocks progress, must fix immediately
🟡 HIGH - Important, should do soon
🟢 MEDIUM - Nice to have, can wait
⚪ LOW - Optional, future enhancement

✅ Quality Checklist

Before considering phase documentation complete, verify:

Frontmatter

All files have complete frontmatter
Dates and times are accurate
Status reflects current state
Icons are appropriate
Order numbers are sequential

Content

Headers are simple (no complex formatting)
Code examples use proper syntax highlighting
Links use absolute paths without extensions
No /english/ or /public/ in URLs
Mermaid/D3 graphs where helpful

Structure

All 5 required files present
Files follow naming conventions
Progress notes use ALL CAPS naming
Internal links work correctly
Parent documentation links to phase

Documentation Scan

Ran yarn docs:scan after creating phase
Phase appears in documentation system
All files accessible via navigation

🎯 Success Metrics

A well-documented phase should enable ANY AI agent (or human developer) to:

Understand Context - Know what was done and why
Track Progress - See exactly where things stand
Continue Work - Pick up where the previous agent left off
Measure Success - Know when phase is complete
Learn Patterns - Understand architectural decisions

📚 Examples

See these phases for reference:

Phase 8 - Polish, Real AI, Production Launch
Phase 9 - Production Perfection & Launch
Universe Restructure Phase 1 - Example with context folder

Note: The universe-restructure phase-1 has an excellent context/ folder demonstrating how to preserve historical documentation.

🔗 Related Documentation

AGENTS.md - General documentation rules
Documentation Guide - Overall project documentation
Template Location - Main template system

Template Location: /docs/english/Templates/phases-template/
Last Updated: November 10, 2025
Status: ✅ TEMPLATE READY FOR USE
Version: 1.1 (Added context folder support)

Phase Documentation Template

🤖 Quick Start: Automated Creation

📋 Template Structure

📁 Context Folder (Critical for AI Agents)

🎯 When to Create a New Phase

📝 File-by-File Instructions

1. index.mdc - Phase Overview

2. PHASE-X-COMPLETE-PLAN.md - Implementation Plan

3. achievements.md - Feature Completion Tracking

4. progress.md - Daily Progress Notes

5. next-steps.md - Immediate Action Items

🎨 Naming Conventions

File Names

Progress Notes Files

🔄 Workflow for AI Agents

Starting a New Phase

During Phase Execution

Completing a Phase

📊 Progress Tracking Guidelines

Visual Progress Bars

Status Emojis

Priority Indicators

✅ Quality Checklist

Frontmatter

Content

Structure

Documentation Scan

🎯 Success Metrics

📚 Examples

🔗 Related Documentation

1. `index.mdc` - Phase Overview

2. `PHASE-X-COMPLETE-PLAN.md` - Implementation Plan

3. `achievements.md` - Feature Completion Tracking

4. `progress.md` - Daily Progress Notes

5. `next-steps.md` - Immediate Action Items