Refactor custom steps to support strongly-typed placement positions

.github/workflows/test-post-steps.md

@@ -1,6 +1,6 @@
 ---
-# Test workflow for post-steps functionality
-# This workflow validates that post-steps compile correctly and are properly indented
+# Test workflow for post-agent steps functionality
+# This workflow validates that post-agent steps compile correctly and are properly indented
 
 on:
   workflow_dispatch:
@@ -16,33 +16,34 @@ tools:
     allowed: [get_repository]
 
 # Steps that run after AI execution
-post-steps:
-  - name: Verify Post-Steps Execution
-    run: |
-      echo "✅ Post-steps are executing correctly"
-      echo "This step runs after the AI agent completes"
-
-  - name: Upload Test Results
-    if: always()
-    uses: actions/upload-artifact@v4
-    with:
-      name: post-steps-test-results
-      path: /tmp/gh-aw/
-      retention-days: 1
-      if-no-files-found: ignore
-
-  - name: Final Summary
-    run: |
-      echo "## Post-Steps Test Summary" >> $GITHUB_STEP_SUMMARY
-      echo "✅ All post-steps executed successfully" >> $GITHUB_STEP_SUMMARY
-      echo "This validates the post-steps indentation fix" >> $GITHUB_STEP_SUMMARY
+steps:
+  post-agent:
+    - name: Verify Post-Agent Steps Execution
+      run: |
+        echo "✅ Post-agent steps are executing correctly"
+        echo "This step runs after the AI agent completes"
+
+    - name: Upload Test Results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: post-steps-test-results
+        path: /tmp/gh-aw/
+        retention-days: 1
+        if-no-files-found: ignore
+
+    - name: Final Summary
+      run: |
+        echo "## Post-Agent Steps Test Summary" >> $GITHUB_STEP_SUMMARY
+        echo "✅ All post-agent steps executed successfully" >> $GITHUB_STEP_SUMMARY
+        echo "This validates the post-agent steps indentation fix" >> $GITHUB_STEP_SUMMARY
 
 timeout_minutes: 5
 ---
 
-# Test Post-Steps Workflow
+# Test Post-Agent Steps Workflow
 
-This is a test workflow to validate that post-steps compile correctly with proper YAML indentation.
+This is a test workflow to validate that post-agent steps compile correctly with proper YAML indentation.
 
 ## Your Task
 

docs/src/content/docs/reference/frontmatter-full.md

@@ -771,28 +771,31 @@ network:
 # (optional)
 if: "example-value"
 
-# Custom workflow steps
+# Custom workflow steps. Can be an array (legacy format, goes to pre-agent
+# position) or an object with named positions (pre, pre-agent, post-agent, post)
 # (optional)
 # This field supports multiple formats (oneOf):
 
-# Option 1: object
+# Option 1: Object format with named step positions
 steps:
-  {}
+  # Steps to run before checkout and runtime setup
+  # (optional)
+  pre: []
 
-# Option 2: array
-steps: []
-  # Array items: undefined
+  # Steps to run after setup but before agent execution
+  # (optional)
+  pre-agent: []
 
-# Custom workflow steps to run after AI execution
-# (optional)
-# This field supports multiple formats (oneOf):
+  # Steps to run immediately after agent execution
+  # (optional)
+  post-agent: []
 
-# Option 1: object
-post-steps:
-  {}
+  # Steps to run after all other steps are complete
+  # (optional)
+  post: []
 
-# Option 2: array
-post-steps: []
+# Option 2: Legacy array format (steps go to pre-agent position)
+steps: []
   # Array items: undefined
 
 # AI engine configuration that specifies which AI processor interprets and