feat: Add README documentation for cmd/samples/recipes

cmd/samples/recipes/branch/README.md

@@ -0,0 +1,108 @@
+# Branch Sample
+
+This sample demonstrates **parallel execution** - running multiple activities concurrently using two different approaches.
+
+> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for a step-by-step tutorial with screenshots.
+
+## Two Approaches to Parallelism
+
+### 1. Futures (`-c branch`)
+Execute activities in parallel, collect futures, then wait for all:
+
+```
+     ┌─────────────┐
+     │   Start     │
+     └──────┬──────┘
+   ┌────────┼────────┐
+   ▼        ▼        ▼
+┌─────┐  ┌─────┐  ┌─────┐
+│ A1  │  │ A2  │  │ A3  │   (parallel)
+└──┬──┘  └──┬──┘  └──┬──┘
+   └────────┼────────┘
+            ▼
+     ┌─────────────┐
+     │ Wait all    │
+     └─────────────┘
+```
+
+### 2. Coroutines (`workflow.Go`)
+Spawn goroutine-like coroutines with channels for coordination:
+
+```
+     ┌─────────────┐
+     │   Start     │
+     └──────┬──────┘
+        ┌───┴───┐
+        ▼       ▼
+   ┌─────────┐ ┌─────┐
+   │ A1 → A2 │ │ A3  │   (parallel branches)
+   └────┬────┘ └──┬──┘
+        └────┬────┘
+             ▼
+     ┌─────────────┐
+     │ channel.Receive │
+     └─────────────┘
+```
+
+## Prerequisites
+
+1. Cadence server running (see [main README](../../../../README.md))
+2. Build the samples: `make`
+
+## Running the Sample
+
+```bash
+# Terminal 1: Start worker
+./bin/branch -m worker
+
+# Terminal 2: Trigger workflows
+./bin/branch -m trigger              # Coroutines approach (default)
+./bin/branch -m trigger -c branch    # Futures approach
+```
+
+## Key Code
+
+### Futures Pattern
+```go
+var futures []workflow.Future
+for i := 1; i <= totalBranches; i++ {
+    future := workflow.ExecuteActivity(ctx, sampleActivity, input)
+    futures = append(futures, future)
+}
+// Wait for all
+for _, future := range futures {
+    future.Get(ctx, nil)
+}
+```
+
+### Coroutines Pattern
+```go
+waitChannel := workflow.NewChannel(ctx)
+
+workflow.Go(ctx, func(ctx workflow.Context) {
+    workflow.ExecuteActivity(ctx, activity1).Get(ctx, nil)
+    workflow.ExecuteActivity(ctx, activity2).Get(ctx, nil)
+    waitChannel.Send(ctx, "done")
+})
+
+workflow.Go(ctx, func(ctx workflow.Context) {
+    workflow.ExecuteActivity(ctx, activity3).Get(ctx, nil)
+    waitChannel.Send(ctx, "done")
+})
+
+// Wait for both coroutines
+waitChannel.Receive(ctx, nil)
+waitChannel.Receive(ctx, nil)
+```
+
+## Testing
+
+```bash
+go test -v ./cmd/samples/recipes/branch/
+```
+
+## References
+
+- [Parallel Execution](https://cadenceworkflow.io/docs/go-client/execute-activity/)
+- [Workflow Coroutines](https://cadenceworkflow.io/docs/go-client/workflow-patterns/)
+

cmd/samples/recipes/cancelactivity/README.md

@@ -0,0 +1,60 @@
+# Cancel Activity Sample
+
+This sample demonstrates **graceful activity cancellation** with cleanup operations.
+
+> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
+
+## How It Works
+
+```
+┌──────────────────┐
+│ Start Workflow   │
+└────────┬─────────┘
+         ▼
+┌──────────────────┐     ┌──────────────────┐
+│ activityToBe     │────▶│ User cancels     │
+│ Canceled()       │     │ workflow         │
+│ (heartbeating)   │     └────────┬─────────┘
+└──────────────────┘              │
+         │◀───────────────────────┘
+         ▼
+┌──────────────────┐
+│ cleanupActivity()│  (runs via NewDisconnectedContext)
+└──────────────────┘
+```
+
+## Prerequisites
+
+1. Cadence server running (see [main README](../../../../README.md))
+2. Build the samples: `make`
+
+## Running the Sample
+
+```bash
+# Terminal 1: Start worker
+./bin/cancelactivity -m worker
+
+# Terminal 2: Trigger workflow
+./bin/cancelactivity -m trigger
+
+# Terminal 3: Cancel the workflow (copy WorkflowID from trigger output)
+./bin/cancelactivity -m cancel -w <WorkflowID>
+```
+
+## Key Code
+
+```go
+defer func() {
+    if cadence.IsCanceledError(retError) {
+        newCtx, _ := workflow.NewDisconnectedContext(ctx)
+        workflow.ExecuteActivity(newCtx, cleanupActivity).Get(ctx, nil)
+    }
+}()
+```
+
+## Testing
+
+```bash
+go test -v ./cmd/samples/recipes/cancelactivity/
+```
+

cmd/samples/recipes/childworkflow/README.md

@@ -0,0 +1,89 @@
+# Child Workflow Sample
+
+This sample demonstrates **parent-child workflow relationships** and the **ContinueAsNew** pattern for long-running workflows.
+
+> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for a step-by-step tutorial with screenshots.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 Parent Workflow                      │
+│  ExecuteChildWorkflow(child, 0, 5)                  │
+│                      │                               │
+│                      ▼                               │
+│  ┌─────────────────────────────────────────────┐    │
+│  │           Child Workflow                     │    │
+│  │  Run 1 → ContinueAsNew                       │    │
+│  │  Run 2 → ContinueAsNew                       │    │
+│  │  Run 3 → ContinueAsNew                       │    │
+│  │  Run 4 → ContinueAsNew                       │    │
+│  │  Run 5 → Complete ✓                          │    │
+│  └─────────────────────────────────────────────┘    │
+│                      │                               │
+│                      ▼                               │
+│  Parent receives: "completed after 5 runs"          │
+└─────────────────────────────────────────────────────┘
+```
+
+**Use cases:**
+- Breaking large workflows into modular pieces
+- Long-running workflows that need to reset history (ContinueAsNew)
+- Workflow decomposition for better organization
+
+## Prerequisites
+
+1. Cadence server running (see [main README](../../../../README.md))
+2. Build the samples: `make`
+
+## Running the Sample
+
+```bash
+# Terminal 1: Start worker
+./bin/childworkflow -m worker
+
+# Terminal 2: Trigger workflow
+./bin/childworkflow -m trigger
+```
+
+## Key Code
+
+### Parent Workflow
+```go
+cwo := workflow.ChildWorkflowOptions{
+    WorkflowID:                   childID,
+    ExecutionStartToCloseTimeout: time.Minute,
+}
+ctx = workflow.WithChildOptions(ctx, cwo)
+
+var result string
+err := workflow.ExecuteChildWorkflow(ctx, sampleChildWorkflow, 0, 5).Get(ctx, &result)
+```
+
+### Child Workflow with ContinueAsNew
+```go
+func sampleChildWorkflow(ctx workflow.Context, totalCount, runCount int) (string, error) {
+    totalCount++
+    runCount--
+
+    if runCount == 0 {
+        return fmt.Sprintf("completed after %v runs", totalCount), nil
+    }
+
+    // Restart workflow with new parameters (resets history)
+    return "", workflow.NewContinueAsNewError(ctx, sampleChildWorkflow, totalCount, runCount)
+}
+```
+
+## Why ContinueAsNew?
+
+Workflow history grows with each event. For long-running workflows, use `ContinueAsNew` to:
+- Reset the history size
+- Prevent hitting history limits
+- Keep workflows performant
+
+## References
+
+- [Child Workflows](https://cadenceworkflow.io/docs/go-client/child-workflows/)
+- [ContinueAsNew](https://cadenceworkflow.io/docs/go-client/continue-as-new/)
+

cmd/samples/recipes/choice/README.md

@@ -0,0 +1,105 @@
+# Choice Sample
+
+This sample demonstrates **conditional workflow logic** - executing different activities based on runtime decisions.
+
+> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for a step-by-step tutorial with screenshots.
+
+## Two Patterns
+
+### 1. Exclusive Choice (`-c single`)
+Execute ONE activity based on a decision:
+
+```
+┌───────────────┐
+│ getOrder()    │
+│ returns "apple"│
+└───────┬───────┘
+        │
+   ┌────┴────┬────────┬────────┐
+   ▼         ▼        ▼        ▼
+┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
+│apple │ │banana│ │cherry│ │orange│
+│  ✓   │ │      │ │      │ │      │
+└──────┘ └──────┘ └──────┘ └──────┘
+```
+
+### 2. Multi Choice (`-c multi`)
+Execute MULTIPLE activities in parallel based on a basket:
+
+```
+┌───────────────────┐
+│ getBasketOrder()  │
+│ returns ["apple", │
+│  "cherry","orange"]│
+└─────────┬─────────┘
+    ┌─────┼─────┐
+    ▼     ▼     ▼
+┌──────┐┌──────┐┌──────┐
+│apple ││cherry││orange│  (parallel)
+│  ✓   ││  ✓   ││  ✓   │
+└──────┘└──────┘└──────┘
+```
+
+## Prerequisites
+
+1. Cadence server running (see [main README](../../../../README.md))
+2. Build the samples: `make`
+
+## Running the Sample
+
+```bash
+# Terminal 1: Start worker
+./bin/choice -m worker
+
+# Terminal 2: Trigger workflows
+./bin/choice -m trigger -c single    # Exclusive choice (default)
+./bin/choice -m trigger -c multi     # Multi choice
+```
+
+## Key Code
+
+### Exclusive Choice
+```go
+var orderChoice string
+workflow.ExecuteActivity(ctx, getOrderActivity).Get(ctx, &orderChoice)
+
+switch orderChoice {
+case "apple":
+    workflow.ExecuteActivity(ctx, orderAppleActivity, orderChoice)
+case "banana":
+    workflow.ExecuteActivity(ctx, orderBananaActivity, orderChoice)
+// ...
+}
+```
+
+### Multi Choice
+```go
+var choices []string
+workflow.ExecuteActivity(ctx, getBasketOrderActivity).Get(ctx, &choices)
+
+var futures []workflow.Future
+for _, item := range choices {
+    switch item {
+    case "apple":
+        f = workflow.ExecuteActivity(ctx, orderAppleActivity, item)
+    // ...
+    }
+    futures = append(futures, f)
+}
+
+// Wait for all
+for _, future := range futures {
+    future.Get(ctx, nil)
+}
+```
+
+## Testing
+
+```bash
+go test -v ./cmd/samples/recipes/choice/
+```
+
+## References
+
+- [Cadence Documentation](https://cadenceworkflow.io)
+