Add task initialization guidance to Claude skills (#10)

Author: milldr

internal/agents/defaults/claude/CLAUDE.md

@@ -6,6 +6,10 @@ You are working inside a **flow workspace** — a multi-repo development environ
 
 Flow manages multi-repo development workspaces using git worktrees. A YAML manifest (`state.yaml`) defines which repos and branches belong together, and `flow render` materializes the workspace by cloning repos and creating worktrees.
 
+## Getting Started
+
+If this is a fresh workspace with no repos yet, the user will give you a task — possibly pasted from Slack, dictated, or described in plain language. Use the **Task Initialization** section in the `flow-cli` skill to set the workspace name, description, add repos, render, and start working. You have everything you need to bootstrap the workspace yourself.
+
 ## How this workspace is structured
 
 Each workspace directory contains:

internal/agents/defaults/claude/skills/flow-cli/SKILL.md

@@ -6,6 +6,42 @@ user-invocable: false
 
 # Flow CLI
 
+## Task Initialization
+
+When you are launched into a fresh workspace with no repos, your first job is to set up the workspace for the task. The user may paste a message from Slack, dictate a prompt, or describe the work in plain language. Follow these steps:
+
+1. **Understand the task**: Read the user's prompt. Identify which repos are needed and what the work involves.
+
+2. **Edit `state.yaml`**: Update the workspace manifest to configure the task:
+   - `metadata.name` — a short, kebab-case name for the task (e.g., `vpc-ipv6`, `fix-auth-bug`)
+   - `metadata.description` — a one-line summary of the task
+   - `spec.repos` — add the repos needed for this task:
+     - `url` — the git remote URL
+     - `branch` — if the user specifies a branch, use it. Otherwise, create a descriptive feature branch name (e.g., `feat/add-ipv6-support`). Flow will automatically create the branch from the repo's default branch if it doesn't already exist in the remote.
+
+3. **Render the workspace**: Run `flow render <workspace>` (using either the workspace ID or name). This clones repos and checks out the specified branches.
+
+4. **Start working**: The repos are now available as directories in the workspace. Begin the task.
+
+### Example
+
+Given a prompt like _"Add IPv6 support to the VPC service — repo is github.com/acme/vpc-service"_:
+
+```yaml
+apiVersion: flow/v1
+kind: State
+metadata:
+  name: vpc-ipv6
+  description: Add IPv6 support to the VPC service
+  created: "2026-02-24T00:00:00Z"
+spec:
+  repos:
+    - url: github.com/acme/vpc-service
+      branch: feat/ipv6-support
+```
+
+Then run `flow render vpc-ipv6` to materialize the workspace and start coding.
+
 ## Common Commands
 
 | Command | Description |