AI Agent Phase Creation Workflow

Step-by-step guide for AI agents creating phase documentation

🤖 AI Agent Phase Creation Workflow

For AI Agents: Follow this step-by-step workflow to create perfect phase documentation.

📋 Prerequisites

Before starting:

Previous phase is ≥80% complete OR natural breakpoint reached
READ the previous phase's context/ folder ⚠️ CRITICAL
Clear understanding of new phase goals
Access to project context and history
Templates available in /Templates/phases-template/ folder

🚀 Phase 1: Planning (20 minutes)

Step 1.1: Read Context Folder FIRST ⚠️ CRITICAL

1. Navigate to previous phase's context/ folder
2. Read ALL files in context folder:
   - Session completion reports
   - Integration status documents
   - Achievement summaries
   - Honest status assessments
   - Realistic roadmaps
3. Take notes on:
   - What was actually completed
   - What decisions were made
   - What blockers were encountered
   - What's carried forward

Output: Deep understanding of previous work

Example:

cd ../phase-[previous]/context/
ls -la
cat COMPLETE-INTEGRATION-STATUS-*.md
cat FINAL-SESSION-REPORT-*.md
cat HONEST-STATUS-ASSESSMENT-*.md

Step 1.2: Analyze Current State

1. Review previous phase achievements (from context)
2. Identify carried-forward features
3. Calculate completion percentage
4. List remaining work

Output: Clear understanding of starting point

Step 1.3: Define Phase Scope

1. Identify 3-5 main focus areas
2. Estimate time for each area (hours)
3. Define success criteria (5-7 items)
4. Set target completion date

Output: Phase boundaries and goals

Step 1.4: Choose Phase Number

1. Check existing phases
2. Use next sequential number
3. Create descriptive phase name

Example: phase-10 for "Production Optimization"

📁 Phase 2: Structure Creation (2 minutes with automation!)

Step 2.1: Use Automated Script ⚡ RECOMMENDED

# Navigate to templates directory
cd /docs/english/Templates/phases-template/

# Run the intelligent automation script
./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 Phase"

What the script does automatically:

✅ Creates phase-X/ folder
✅ Creates context/ subfolder with README
✅ Copies all 5 template files
✅ Renames templates appropriately
✅ Fills in dates, times, and phase numbers
✅ Checks for previous phase context
✅ Optionally runs yarn docs:scan

Result: Complete phase structure in ~30 seconds!

Step 2.2: Manual Method (Alternative)

Click to expand manual steps (not recommended)

# Create phase folder with context
cd /docs/english/[ProjectName]/phases/
mkdir phase-X
cd phase-X
mkdir context  # Create context folder immediately!

# Copy all template files from Templates folder
cp /docs/english/Templates/phases-template/index.template.mdc ./index.mdc
cp /docs/english/Templates/phases-template/PHASE-X-COMPLETE-PLAN.template.md ./PHASE-X-COMPLETE-PLAN.md
cp /docs/english/Templates/phases-template/achievements.template.md ./achievements.md
cp /docs/english/Templates/phases-template/progress.template.md ./progress.md
cp /docs/english/Templates/phases-template/next-steps.template.md ./next-steps.md

Note: Manual method requires more customization work. Use the automated script instead!

✍️ Phase 3: Content Generation (60-90 minutes)

Step 3.1: Customize `index.mdc` (15 min)

Required Changes:

Frontmatter:

title: Phase X - [Descriptive Name]
description: [One sentence goal]
icon: [Choose emoji: 🎯/🚀/🌟/💎/⚡]
created: [Current date]
updated: [Current date and time]
status: 🎯 PLANNED
purpose: [What this phase achieves]
order: 1
tags: [phase-X, primary-tag, secondary-tag, tertiary-tag]

Content:
- Replace [Phase X] with actual number
- Fill in timeline and goal
- List 3-5 focus areas
- Update "What's Working" from previous phase
- List "What Needs Work" for this phase
- Define success criteria
- Write inspiring vision statement

Verification:

All placeholders replaced
Dates accurate
Links point to correct files
Success criteria measurable

Step 3.2: Customize `PHASE-X-COMPLETE-PLAN.md` (30 min)

Required Changes:

Frontmatter: Update all fields
Gap Analysis: List what works vs. what needs work
Implementation Schedule:
- Break down by days/weeks
- Include time estimates
- Add code examples where relevant
- Specify file locations
Acceptance Criteria: Comprehensive checklists
Timeline Table: Day-by-day breakdown
The Vision: End-user experience

Tips:

Be specific with file paths
Include actual code examples
Reference real components/services
Add test scenarios

Verification:

All days/weeks planned
Time estimates realistic
Code examples valid
File paths correct

Step 3.3: Customize `achievements.md` (10 min)

Required Changes:

Frontmatter: Update dates and status
Major Milestones: Define 3-5 milestones
Feature Lists: Use checkboxes
Carried Forward: Copy from previous phase
Progress Bars: Initialize to 0%

Example Milestone:

### Milestone 1: Core Feature Complete ⏳ Pending
**Target**: Day 1-3
**Impact**: Users can perform X

**Features**:
- [ ] Feature A
- [ ] Feature B
- [ ] Feature C

**When Complete**: Users can successfully X

Verification:

Milestones aligned with plan
Features specific and measurable
Progress bars formatted correctly

Step 3.4: Customize `progress.md` (10 min)

Required Changes:

Frontmatter: Current date/time
Overall Progress: Initialize bars to 0%
Day 0 Entry: Planning session details
Milestones Section: Copy from achievements
Current Focus: First immediate action

Day 0 Template:

### Day 0: [Month Day, Year] [Time] - Phase X Planning

**Activities**:
- ✅ Analyzed previous phase completion
- ✅ Created Phase X documentation structure
- ✅ Identified focus areas
- ✅ Planned implementation approach

**Carried Forward from Phase [Y]**:
- ✅ [Feature 1]
- ✅ [Feature 2]
- ✅ [Feature 3]

**Next Steps**:
- [First action]
- [Second action]
- [Third action]

**Time Spent**: 1 hour (planning)

Verification:

Day 0 entry complete
Progress bars initialized
Next steps defined

Step 3.5: Customize `next-steps.md` (15 min)

Required Changes:

Frontmatter: Current date/time
Immediate Actions: Top 3-5 actions with priorities
This Week Plan: Day-by-day breakdown
Success Criteria: When phase complete

Action Template:

### 1. [Action Name] 🔴 CRITICAL
**Issue**: [Problem description]
**Time**: [X] hours
**Priority**: CRITICAL

**Problem**:
- [Detail 1]
- [Detail 2]

**Solution**:
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Test**:

[Test step]
[Verify result]

Verification:

Actions prioritized correctly
Time estimates realistic
Test criteria defined
Week plan complete

🔗 Phase 4: Integration (15 minutes)

Step 4.1: Update Parent Index

File: docs/english/GoGrab-Space/user-journey/phases/index.mdc

Add entry:

### Phase X: [Phase Name]
**Status**: 🎯 In Progress
**Timeline**: [Duration]

[Brief description]

[Documentation →](/GoGrab-Space/user-journey/phases/phase-X/index)

Step 4.2: Link Previous Phase

File: phase-[X-1]/index.mdc

Add at bottom:

## Next Phase

Continue to [Phase X: [Name]](/GoGrab-Space/user-journey/phases/phase-X/index)

Step 4.3: Link Current Phase Back

File: phase-X/index.mdc

In Documentation section:

### Reference
- [Previous Phase](/GoGrab-Space/user-journey/phases/phase-[X-1]/index)

🧪 Phase 5: Verification (10 minutes)

Step 5.1: Content Check

✓ All placeholders replaced with actual content
✓ Dates and times accurate
✓ File names follow conventions
✓ Frontmatter complete in all files
✓ Status indicators appropriate
✓ Code blocks properly formatted
✓ Links use correct format (no .md, no /english/)

Step 5.2: Link Check

Test all links:
✓ Internal phase links work
✓ Links to previous phase work
✓ Links to parent documentation work
✓ Code file paths exist

Step 5.3: Run Documentation Scan

cd /Users/fguijarro/developer/repos/editor
yarn docs:scan

Expected output:

✓ Found phase-X/index.mdc
✓ Found phase-X/PHASE-X-COMPLETE-PLAN.md
✓ Found phase-X/achievements.md
✓ Found phase-X/progress.md
✓ Found phase-X/next-steps.md
✓ Documentation manifest updated

Step 5.4: Visual Verification

1. Open docs-angular app (port 5010)
2. Navigate to new phase
3. Verify all links work
4. Check formatting renders correctly
5. Verify frontmatter displays properly

📝 Phase 6: First Work Session

Before Starting Work

ALWAYS review context/ folder for:

Previous decisions
Known issues
Architectural choices
What was tried before

Update After First Session

File: progress.md

### Day 1: [Month Day, Year] [Time] - [Session Focus]

**Activities**:
- ✅ [Completed task 1]
- ✅ [Completed task 2]
- 🚀 [In-progress task 3]

**Technical Notes**:
[Any important details]

**Next Steps**:
- [Next action]

**Time Spent**: [X] hours

File: next-steps.md

Check off completed actions
Add new immediate actions
Update priorities

🎯 Ongoing Maintenance

After Every Work Session

1. Update progress.md with session notes
2. Update progress bars in progress.md
3. Check off completed items in next-steps.md
4. Add new actions if discovered

After Milestone Completion

1. Update achievements.md:
   - Check off completed features
   - Add to achievement log
   - Update progress bars
2. Update index.mdc if status changes
3. Consider running docs:scan if major changes

Daily

1. Review next-steps.md
2. Update priorities if needed
3. Plan next work session
4. Update time estimates if needed

🏁 Completing a Phase

Final Updates

1. Mark all checkboxes as complete
2. Update all status fields to "✅ COMPLETE"
3. Add final timestamps
4. Create completion summary in progress.md
5. Update parent index status

Archive Important Documents to Context Folder

1. Move/copy final session report to context/
2. Add integration status document to context/
3. Add honest status assessment to context/
4. Add any breakthrough implementation notes to context/
5. This preserves context for future AI agents!

Example:

cd phase-X/context/
# Add final documentation
cp ../FINAL-SESSION-REPORT.md ./FINAL-SESSION-REPORT-NOV-10-2025.md
cp ../INTEGRATION-STATUS.md ./INTEGRATION-STATUS-NOV-10-2025.md

Create Next Phase

1. READ current phase's context folder
2. Review remaining work (if any)
3. Plan next focus areas
4. Run this workflow again for Phase X+1
5. Remember to create context/ folder in new phase!

📊 Success Metrics

A well-created phase documentation enables:

✅ Context Understanding - Anyone can understand what's happening
✅ Progress Tracking - Clear visibility into status
✅ Continuation - Another agent can pick up work seamlessly
✅ Success Measurement - Know when phase is complete
✅ Learning - Understand decisions and patterns

🆘 Troubleshooting

Issue: Documentation Not Appearing

Solution:
1. Verify frontmatter syntax (valid YAML)
2. Run yarn docs:scan again
3. Check for typos in file names
4. Ensure files in correct directory

Issue: Links Not Working

Solution:
1. Remove .md extensions from links
2. Remove /english/ prefix
3. Use absolute paths starting with /
4. Verify target files exist

Issue: Progress Bars Not Rendering

Solution:
1. Ensure bars use █ and ░ characters
2. Check spacing: [████░░] not [▓▓▓▓░░]
3. Format: [bar] percent (x/y)

📚 Resources

Templates: /Templates/phases-template/
Examples:
- Phase 8
- Phase 9
- Universe Restructure Phase 1 - Has excellent context folder!
Quick Reference: QUICK-REFERENCE.md
Documentation System: AGENTS.md

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

🤖 AI Agent Phase Creation Workflow

📋 Prerequisites

🚀 Phase 1: Planning (20 minutes)

Step 1.1: Read Context Folder FIRST ⚠️ CRITICAL

Step 1.2: Analyze Current State

Step 1.3: Define Phase Scope

Step 1.4: Choose Phase Number

📁 Phase 2: Structure Creation (2 minutes with automation!)

Step 2.1: Use Automated Script ⚡ RECOMMENDED

Step 2.2: Manual Method (Alternative)

✍️ Phase 3: Content Generation (60-90 minutes)

Step 3.1: Customize index.mdc (15 min)

Step 3.2: Customize PHASE-X-COMPLETE-PLAN.md (30 min)

Step 3.3: Customize achievements.md (10 min)

Step 3.4: Customize progress.md (10 min)

Step 3.5: Customize next-steps.md (15 min)

🔗 Phase 4: Integration (15 minutes)

Step 4.1: Update Parent Index

Step 4.2: Link Previous Phase

Step 4.3: Link Current Phase Back

🧪 Phase 5: Verification (10 minutes)

Step 5.1: Content Check

Step 5.2: Link Check

Step 5.3: Run Documentation Scan

Step 5.4: Visual Verification

📝 Phase 6: First Work Session

Before Starting Work

Update After First Session

🎯 Ongoing Maintenance

After Every Work Session

After Milestone Completion

Daily

🏁 Completing a Phase

Final Updates

Archive Important Documents to Context Folder

Create Next Phase

📊 Success Metrics

🆘 Troubleshooting

Issue: Documentation Not Appearing

Issue: Links Not Working

Issue: Progress Bars Not Rendering

📚 Resources

Step 3.1: Customize `index.mdc` (15 min)

Step 3.2: Customize `PHASE-X-COMPLETE-PLAN.md` (30 min)

Step 3.3: Customize `achievements.md` (10 min)

Step 3.4: Customize `progress.md` (10 min)

Step 3.5: Customize `next-steps.md` (15 min)