User & AI Guide: Autonomous Project Execution in Valstorm

This guide explains how users and AI agents collaborate within Valstorm to plan, scaffold, execute, and review structured work using Projects, Phases, and Tasks.

Whether you are prompting an AI agent to build out a complex project plan from scratch or kicking off autonomous execution, this document serves as the operational contract for both humans and AI.

1. The Core Mental Model

Valstorm bridges human strategic vision and autonomous agent execution through a 3-tier hierarchy:

1. Project (project): The top-level container for a major initiative or deliverable (e.g., "Migrate Cloud Infrastructure" or "Launch Q3 Marketing Campaign"). It holds the master execution pipeline (stage_order) and tracks overall progress.
2. Phase (phase): Major sequential milestones within a project (e.g., "Phase 1: Discovery & Audit"). Rule: All tasks within a phase must be completed before the system or user triggers a review to advance to the next phase.
3. Task (task): Individual, actionable units of work assigned to phases (e.g., "Export legacy DNS records"). Tasks track status (Not Started, In Progress, Complete, Blocked) and progress percentages.

2. How AI Agents Build Projects (Scaffolding)

When you ask an AI agent to set up a project, the agent uses Valstorm's structured APIs to automatically scaffold the entire hierarchy in seconds.

Example User Prompt:

"Hey Valstorm, I need to plan a security audit for our staging environment. Create a project with three phases: Audit, Remediation, and Verification, with specific tasks for each."

What the AI Agent Does Behind the Scenes:

1. Creates the Project Record: Calls the database to create a new project with a title, description, and initial status (Draft or In Progress).
2. Scaffolds Phases & Tasks: Creates phase records linked to the project and populates each phase with structured task items.
3. Establishes Execution Pipeline: Automatically populates the project’s stage_order array so the AI and user have a strict, ordered roadmap to follow.
4. Links AI Chat Context: Associates a dedicated ai_chat session with the project so all subsequent agent actions and telemetry are tracked.

3. Autonomous Execution Workflow

Once a project is scaffolded, the workflow follows a cyclical, human-in-the-loop pattern designed for autonomous agent work:

Step 1: Kickoff & Initialization

• Action: The user (or AI upon prompt) initiates the project execution (action="start").
• AI Behavior: The AI agent loads the project context, inspects current_stage, identifies the active phase and its pending tasks, and prepares to execute the work.

Step 2: Agentic Work Execution

• Action: The AI agent works through the tasks in the current active phase. It can run code, interact with APIs, generate documents, or perform system operations.
• Tracking: As tasks are worked on, their status updates to In Progress and eventually Complete (with progress set to 100%).

Step 3: Phase Review & Advancement

• Action: Once all tasks in the current phase are marked complete, the project pauses for review.
• User Review: The user inspects the completed phase outputs in the Project Dashboard (ProjectDashboardView).
• Advancement (action="advance"): Once approved, the user (or agent) triggers the stage advancement. The system marks the current phase as Complete and automatically shifts current_stage to the next phase in the pipeline.

4. Best Practices for Prompting AI Agents on Projects

To ensure your AI agents successfully manage and execute projects without getting stuck, follow these prompting guidelines:

1. Be Specific About Milestones and Phases

• Weak Prompt: "Help me build a website."
• Strong Prompt: "Create a Valstorm project called 'Marketing Website Redesign' with 3 distinct phases: 1. Wireframing, 2. Frontend Development, 3. SEO Optimization. Include at least 3 detailed tasks per phase."

2. Instruct the Agent to Use the Project Orchestrator

• When working with an active project, tell the agent:

  "Start the project orchestration for project ID proj_..., review the current active phase, and execute the next pending task."

3. Leverage Human Review Gates

• Remind the agent that Phases are review gates. Instruct the agent:

  "Complete all tasks in Phase 1, mark the phase as ready for review, and pause until I approve the transition to Phase 2."

Summary for the Public Knowledge Base

By standardizing Projects, Phases, and Tasks, Valstorm enables users to delegate entire operational workflows to AI agents. You talk, the AI scaffolds the roadmap, the agent executes task-by-task, and you maintain complete control at every phase review gate.