beam-ai-team/execute-project

Execute Build

Execute build work systematically with progress tracking.

Safety Contract

Before updating build progress, bulk-completing tasks, changing status, or writing project artifacts, show the build ID/path, current section, files to change, task count, and whether --no-confirm will be used. Require explicit user approval in the current turn before writing or overwriting local files. Reading build context and reporting status do not require approval.

Workflow

1. Load Context

beam-next-load --build [ID]

Read files from _usage.recommended_reads.

2. Show Status

----------------------------------
PROJECT: [Name]
----------------------------------
Progress: [X]/[Y] tasks ([Z]%)
Current: Section [N] - [Name]
Next: [Task description]
----------------------------------

3. Find Current State

Parse steps.md for:

• First uncompleted section (## Section/Phase N)
• Next uncompleted task (- [ ])

4. Execute Section

Work through tasks in current section. Show after each:

[OK] Task [N] complete!

5. Bulk-Complete Section

When section done:

beam-next-bulk-archive --build [ID] --section [N] --no-confirm

6. Update Resume State

CRITICAL: After bulk-complete succeeds:

beam-next-update-resume --build [ID] --section [N+1] --completed [total]

Key: Set current_section to NEXT section (not completed one).

7. Continue or Complete

• More sections → repeat from step 4
• User says "pause" → offer partial bulk-complete, trigger close-session
• 100% done → update status to COMPLETE (see below), suggest archive

8. Update Build Status (When Complete)

CRITICAL: Use Edit tool to update status: in 01-planning/01-overview.md.

Valid statuses ONLY: PLANNING, IN_PROGRESS, ACTIVE, COMPLETE, ARCHIVED

# In 01-overview.md frontmatter, change:
status: IN_PROGRESS
# To:
status: COMPLETE

NEVER use: EXECUTION, DONE, FINISHED, or any other value. These are invalid and will cause warnings.

---

Scripts Reference

bulk-complete.py

| Flag | Purpose | |------|---------| | --build ID | Project ID (e.g., "05" or "05-name") | | --all | Complete all tasks | | --section N | Complete section N | | --tasks 1-5,7 | Specific tasks | | --no-confirm | Skip prompt (required for AI) |

Examples:

# Complete section 3
beam-next-bulk-archive --build 05 --section 3 --no-confirm

# Complete specific tasks
beam-next-bulk-archive --build 05 --tasks 1-10,15 --no-confirm

# Complete all
beam-next-bulk-archive --build 05 --all --no-confirm

update-resume.py

| Flag | Purpose | |------|---------| | --build ID | Project ID | | --section N | NEXT section number | | --completed N | Total completed count | | --task N | Current task (optional) | | --phase X | Phase name (optional) |

Example:

# After completing Section 3 (28 total tasks now done)
beam-next-update-resume --build 05 --section 4 --completed 28

---

Resume Context Updates (CRITICAL)

Auto-Synced by Hooks (don't manually update)

These fields are automatically synced by PreCompact hook:

• session_ids - List of all sessions that touched this project
• last_updated - Timestamp of last activity
• total_tasks - Checkbox count from 04-steps.md
• tasks_completed - Completed checkbox count
• current_section - First section with unchecked tasks
• current_task - Position of first unchecked task
• current_phase - "planning" or "execution"
• next_action - "plan-project" or "execute-project"

Claude Must Update

After completing work, update these in resume-context.md:

1. continue_at - Specific pointer for next agent:

   continue_at: "03-working/api.py:142"  # or "Phase 2, Task 3"
   

2. blockers - List any blockers:

   blockers:
     - "Waiting for user decision on auth method"
   

3. files_to_load - Add working files with reason comments:

   files_to_load:
     - "01-planning/04-steps.md"         # Execution checklist
     - "02-resources/decisions.md"       # Key decisions made
     - "03-working/current-file.py"      # Active work in progress
   

Pattern: Create context files → Add to files_to_load:

• Made a decision? → Write to 02-resources/decisions.md → Add to list
• Found a gotcha? → Write to 03-working/session-notes.md → Add to list
• Hook AUTO-LOADS these files in COMPACT mode

4. Context for Next Agent - Prose that POINTS to files:

   ### Latest Session (YYYY-MM-DD)
   
   **Completed this session:**
   - [x] Section N tasks
   - [x] Created working file X
   
   **Key files:**
   - See `decisions.md` for rationale on API design
   - See `session-notes.md` for gotchas discovered
   
   **Next steps:**
   1. Continue at `continue_at` location
   2. Check `blockers` if any
   

Philosophy: Don't capture context in prose. Write it to FILES, add to files_to_load. Prose just POINTS to files.

---

Key Rules (CRITICAL)

1. Section-based execution: Work section by section, not task by task (unless ≤15 total tasks)

2. Bulk-complete after sections: NEVER mark tasks manually with Edit tool

3. Update resume immediately: After EVERY bulk-complete, update resume-context.md Progress Summary

4. Resume points to NEXT: current_section = next section to work on, NOT the one just completed

5. Update files_to_load: Add working files created during execution for context on resume

---

Integration

From plan-project

plan-project completes → User chooses "Execute now"
→ Status updates: PLANNING → IN_PROGRESS
→ execute-project loads immediately (same session)

To close-session

User says "pause" or "done for today"
→ Offer partial bulk-complete
→ Trigger close-session skill

---

Error Handling

| Issue | Solution | |-------|----------| | No task file | Run validate-system skill | | All tasks done | Display "100%!", offer COMPLETE status | | Bad checkbox format | Need - [ ] Task format | | Script fails | Fallback to Edit tool, log error |

---

Display Patterns

Section Complete

----------------------------------
SECTION [N]: [NAME] - COMPLETE!
----------------------------------
Tasks: [X]/[X]
Progress: [████████░░] [Y]%

Continue to Section [N+1], or pause?

Build Complete

----------------------------------
PROJECT COMPLETE!
----------------------------------
All [X] tasks done (100%)
Status → COMPLETE

Use 'archive-project' to archive.