beam-ai-team/setup-workspace

🎯 AI Proactive Triggering (ONBOARDING SKILL)

This is an ONBOARDING skill with HIGH PRIORITY. Natural follow-up after setup-goals.

When to Proactively Suggest (AI MUST check user-config.yaml)

Check learning_tracker.completed.setup_workspace in user-config.yaml. If false:

PROACTIVELY SUGGEST when user:

1. Just completed setup-goals (natural next step)
2. Asks where to save files or how to organize work
3. Creates files in wrong locations (04-workspace/ should be for user content)
4. Mentions file organization, folder structure, or workspace setup
5. Has been using Beam Next for 2+ sessions without workspace setup
6. At menu display when workspace_configured: false

Suggestion Pattern (after setup-goals):

💡 Great, your goals are set! Next recommended step: 'setup workspace' (5-8 min).

This creates a practical folder structure in 04-workspace/ for your files,
tailored to your work patterns. Quick and makes file organization effortless.

Suggestion Pattern (file organization confusion):

💡 I notice you're working with files. Would you like to run 'setup workspace'
(5 min) to create a practical folder structure? It'll help keep your work
organized and make files easier to find.

Menu Integration: When displaying menu with workspace_configured: false:

📁 WORKSPACE
   Not configured ▸ 'setup workspace' (5 min)

DO NOT suggest if:

• learning_tracker.completed.setup_workspace: true
• User has already organized 04-workspace/ manually
• User explicitly prefers ad-hoc organization

---

Setup Workspace

Guide user through workspace folder design using just-in-time organization.

Purpose

Create a practical folder structure in 04-workspace/ based on user's actual work patterns. Follows just-in-time principle: create only what you need now, add more later.

Time Estimate: 5-8 minutes

---

Workflow

Step 1: Understand Context

Read goals.md for role/goals context.

Ask: "What types of files and content will you work with?"

Listen for: document types, client/project categories, research vs output patterns.

---

Step 2: Just-in-Time Principle

Explain briefly:

━━━ KEY PRINCIPLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
"Just-in-time organization": Only create folders you need NOW.
Don't over-organize on day 1. Structure emerges from real work.
We'll start with 3-5 essential folders.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Step 3: Collaborative Design

Based on role, suggest 3-7 folders. Example for sales:

📁 04-workspace/
├── clients/
├── proposals/
├── research/
├── templates/
└── personal-notes/

Iterate until user is satisfied.

---

Step 4: Create Folders

Create agreed structure in 04-workspace/.

---

Step 5: Update Workspace Map

Create/update 04-workspace/workspace-map.md with structure and usage notes:

# Workspace Map

> Auto-generated by setup-workspace skill
> Last updated: {date}

## Folder Structure

{folder tree with descriptions}

## Usage Notes

{any user-specified notes about organization}

---

Step 6: Finalize

Actions (MUST complete all):

1. Create workspace-map.md in 04-workspace/ (if doesn't exist)

2. Mark skill complete in user-config.yaml:

   learning_tracker:
     completed:
       setup_workspace: true  # ADD THIS LINE
   

3. Display completion:

   ✅ Setup Workspace Complete!
   
   Created:
   • {N} folders in 04-workspace/
   • workspace-map.md with structure documentation
   
   Principle: Just-in-time organization. Add folders when needed.
   
   Next steps:
   • 'learn projects' - Understand project workflow
   • 'learn skills' - Create reusable workflows
   • 'create project' - Start your first project
   

4. Prompt close-session:

   💡 When you're done working, say "done" to save progress.
   

---

Success Criteria

• [ ] User's file types/patterns understood
• [ ] 3-7 folders created in 04-workspace/
• [ ] workspace-map.md created with structure documentation
• [ ] learning_tracker.completed.setup_workspace: true in user-config.yaml