speccrew 0.6.68 → 0.7.0

package/.speccrew/skills/speccrew-deploy-smoke-test/workflow.agentflow.xml

@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="deploy-smoke-test" status="pending" version="1.0" desc="Perform lightweight smoke testing against running application">
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="platform_id" required="true" type="string" desc="Platform identifier"/>
+    <field name="base_url" required="false" type="string" desc="Application base URL (e.g., http://localhost:8080). Required for http mode."/>
+    <field name="api_contract_paths" required="false" type="string" desc="Comma-separated paths to API Contract documents. Required for http mode."/>
+    <field name="iteration_path" required="true" type="string" desc="Current iteration directory path"/>
+    <field name="test_mode" required="false" type="string" default="http" desc="Test method: http (default), process, log"/>
+    <field name="expected_exit_code" required="false" type="string" default="0" desc="Expected process exit code for process mode"/>
+    <field name="log_file" required="false" type="string" desc="Log file path for log mode verification"/>
+    <field name="expected_log_patterns" required="false" type="string" desc="Comma-separated regex patterns expected in log for log mode"/>
+    <field name="process_name" required="false" type="string" desc="Process name or pattern to check for process mode"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="mandatory" desc="Smoke test constraints">
+    <field name="text">Smoke test is NOT integration testing — only verify HTTP status codes</field>
+    <field name="text">Pass rate threshold — If pass rate less than 80% then FAILED</field>
+    <field name="text">Critical GET endpoints — If any critical GET endpoint returns 404 then FAILED</field>
+    <field name="text">No business logic testing — Smoke test does not validate request/response bodies</field>
+  </block>
+
+  <!-- ============================================================
+       Test Mode Selection Gateway
+       ============================================================ -->
+  <block type="gateway" id="G0" mode="exclusive" desc="Select test mode execution path">
+    
+    <!-- HTTP Mode (default) -->
+    <branch test="${test_mode} == 'http' OR ${test_mode} == null" name="HTTP Mode">
+      
+      <!-- Step 1: Parse API Contracts -->
+      <block type="task" id="B1" action="analyze" desc="Parse API Contract paths">
+        <field name="input">${api_contract_paths}</field>
+        <field name="split_by">,</field>
+        <field name="output" var="contract_path_list"/>
+      </block>
+
+      <block type="loop" id="L1" over="${contract_path_list}" as="contract_path" desc="Read each API Contract document">
+        <block type="task" action="read-file" desc="Read API Contract">
+          <field name="path">${contract_path}</field>
+          <field name="output" var="contract_content"/>
+        </block>
+      </block>
+
+      <block type="task" id="B2" action="analyze" desc="Extract endpoint list from contracts">
+        <field name="rules">
+          - Parse endpoints from contract:
+            - Method: GET, POST, PUT, DELETE, etc.
+            - Path: endpoint path (e.g., /api/users)
+            - Expected status code: from contract definition
+          - Filter for core endpoints only
+          - For GET endpoints: test directly with full validation
+          - For POST/PUT/DELETE: only verify endpoint exists (expect 400/401/405 is acceptable, NOT 404)
+        </field>
+        <field name="output" var="endpoint_list"/>
+      </block>
+
+      <!-- Step 2: Execute Smoke Tests -->
+      <block type="loop" id="L2" over="${endpoint_list}" as="endpoint" desc="Test each endpoint">
+        <block type="task" action="run-script" desc="Execute curl for endpoint">
+          <field name="command">curl -s -o /dev/null -w "%{http_code}" -X ${endpoint.method} ${base_url}${endpoint.path}</field>
+          <field name="output" var="endpoint.http_status"/>
+        </block>
+      </block>
+
+      <!-- Step 3: Evaluate Results -->
+      <block type="task" id="B3" action="analyze" desc="Apply pass criteria">
+        <field name="rules">
+          - GET endpoints: Pass if HTTP 200 or 301/302 (redirect)
+          - POST/PUT/DELETE endpoints: Pass if NOT 404 (any other status acceptable)
+          - Health endpoint: Pass if HTTP 200
+          - Calculate pass_rate = (passed_count / total_count) * 100
+        </field>
+        <field name="output" var="evaluation_result"/>
+      </block>
+
+      <block type="gateway" id="G1" mode="guard" desc="Check pass rate threshold"
+             test="${evaluation_result.pass_rate} >= 80"
+             fail-action="stop">
+        <field name="message">Smoke test failed with pass rate ${evaluation_result.pass_rate}% (threshold: 80%)</field>
+      </block>
+
+    </branch>
+
+    <!-- Process Mode -->
+    <branch test="${test_mode} == 'process'" name="Process Mode">
+      
+      <block type="task" id="B4" action="run-script" desc="Check process is running">
+        <field name="command">
+          Windows: tasklist /FI "IMAGENAME eq ${process_name}" | findstr /I "${process_name}"
+          Unix/Mac: pgrep -f "${process_name}"
+        </field>
+        <field name="output" var="process_check_result"/>
+      </block>
+
+      <block type="task" id="B5" action="analyze" desc="Verify process stability">
+        <field name="rules">
+          - Record process start time
+          - Wait 10 seconds
+          - Check if process is still running (not crashed)
+          - If process has exited: get exit code and compare with expected_exit_code (default: 0)
+        </field>
+        <field name="output" var="process_stability_result"/>
+      </block>
+
+      <block type="gateway" id="G2" mode="guard" desc="Verify process running"
+             test="${process_stability_result.status} == 'RUNNING' OR ${process_stability_result.exit_code} == ${expected_exit_code}"
+             fail-action="stop">
+        <field name="message">Process verification failed. Process not running or exit code mismatch.</field>
+      </block>
+
+    </branch>
+
+    <!-- Log Mode -->
+    <branch test="${test_mode} == 'log'" name="Log Mode">
+      
+      <block type="task" id="B6" action="read-file" desc="Read log file content">
+        <field name="path">${log_file}</field>
+        <field name="on_fail">STOP - log file not found</field>
+        <field name="output" var="log_content"/>
+      </block>
+
+      <block type="task" id="B7" action="analyze" desc="Parse expected patterns">
+        <field name="input">${expected_log_patterns}</field>
+        <field name="split_by">,</field>
+        <field name="output" var="pattern_list"/>
+      </block>
+
+      <block type="loop" id="L3" over="${pattern_list}" as="pattern" desc="Check each pattern in log">
+        <block type="task" action="run-script" desc="Check pattern in log">
+          <field name="command">
+            Windows: Select-String -Path "${log_file}" -Pattern "${pattern}"
+            Unix/Mac: grep -E "${pattern}" "${log_file}"
+          </field>
+          <field name="output" var="pattern.found"/>
+        </block>
+      </block>
+
+      <block type="task" id="B8" action="analyze" desc="Evaluate log patterns">
+        <field name="rules">
+          - Pass criteria: ALL expected patterns found in log
+          - Fail: Any pattern missing → report which patterns were not found
+        </field>
+        <field name="output" var="log_verification_result"/>
+      </block>
+
+      <block type="gateway" id="G3" mode="guard" desc="Verify all patterns found"
+             test="${log_verification_result.all_patterns_found} == true"
+             fail-action="stop">
+        <field name="message">Log verification failed. Missing patterns: ${log_verification_result.missing_patterns}</field>
+      </block>
+
+    </branch>
+
+  </block>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="status" value="SUCCESS" type="string" desc="Test status"/>
+    <field name="platform_id" from="${platform_id}" type="string" desc="Platform identifier"/>
+    <field name="base_url" from="${base_url}" type="string" desc="Base URL tested"/>
+    <field name="test_mode" from="${test_mode}" type="string" desc="Test mode used"/>
+    <field name="endpoints_tested" from="${endpoint_list.length}" type="number" desc="Number of endpoints tested"/>
+    <field name="pass_rate" from="${evaluation_result.pass_rate}" type="number" desc="Pass rate percentage"/>
+    <field name="passed_count" from="${evaluation_result.passed_count}" type="number" desc="Number of passed tests"/>
+    <field name="failed_count" from="${evaluation_result.failed_count}" type="number" desc="Number of failed tests"/>
+    <field name="test_results" from="${evaluation_result.results}" type="array" desc="Detailed test results"/>
+  </block>
+
+</workflow>

package/.speccrew/skills/speccrew-deploy-startup/SKILL.md

@@ -25,143 +25,11 @@ tools: Read, Bash
 | `log_file` | No | string | Path to application log file (for `log` mode) |
 | `success_pattern` | No | string | Regex pattern in log that indicates successful startup (for `log` mode, e.g., `"Application started"` or `"Ready"`) |
 
-# Workflow
+## AgentFlow Definition
 
-## Step 1: Start Application
+<!-- @agentflow: workflow.agentflow.xml -->
 
-Launch the application in background:
-
-1. **Execute start_cmd in background via Bash**
-   - Working directory: `project_root`
-   - Command: `start_cmd`
-   - Use background execution (e.g., `nohup {start_cmd} > app.log 2>&1 &` on Unix)
-   - Capture the process PID
-
-2. **Record PID for cleanup**
-   - Store PID for later reference
-   - Log: "Application started with PID {pid}"
-
-3. **Wait for initial startup**
-   - Wait 5 seconds for application initialization
-   - Log: "Waiting for application to initialize..."
-
-## Step 2: Verification (Based on Mode)
-
-### Verification Strategy
-
-Based on `verification_mode` parameter:
-
-**Mode: `http`** (default — for server/web applications)
-- Poll `health_url` every 5 seconds using curl
-- Success: HTTP 200 response
-- Timeout: `health_timeout` seconds
-
-**Mode: `process`** (for desktop/mobile/client applications)
-- Check if process `process_name` is running
-- On Windows: `tasklist /FI "IMAGENAME eq {process_name}" | findstr /I "{process_name}"`
-- On Unix/Mac: `pgrep -f "{process_name}"`
-- Success: Process found and running
-- Timeout: `health_timeout` seconds (default 30s)
-
-**Mode: `log`** (for applications with log-based startup confirmation)
-- Monitor `log_file` for `success_pattern`
-- On Windows: `Select-String -Path "{log_file}" -Pattern "{success_pattern}"`
-- On Unix/Mac: `grep -m 1 "{success_pattern}" "{log_file}"`
-- Poll every 3 seconds
-- Success: Pattern found in log
-- Timeout: `health_timeout` seconds (default 60s)
-
-### Execution by Mode
-
-#### HTTP Mode (default)
-
-Poll health endpoint until success or timeout:
-
-1. **Calculate max attempts**
-   - timeout_seconds = parseInt(health_timeout) || 60
-   - max_attempts = timeout_seconds / 5
-   - attempt = 0
-
-2. **Poll health_url**
-   ```bash
-   curl -s -o /dev/null -w "%{http_code}" {health_url}
-   ```
-
-3. **Check response**
-   - HTTP 200 → Health check passed, continue to Step 3
-   - Other codes → Increment attempt, wait 5 seconds, retry
-
-4. **Timeout handling**
-   - If attempt >= max_attempts → FAILED with Error Category: RUNTIME_ERROR
-   - Report: "Health check timed out after {timeout_seconds}s"
-
-#### Process Mode (for client apps)
-
-Verify process is running:
-
-1. **Calculate max attempts**
-   - timeout_seconds = parseInt(health_timeout) || 30
-   - max_attempts = timeout_seconds / 3
-   - attempt = 0
-
-2. **Check process existence**
-   - **Windows**:
-     ```powershell
-     tasklist /FI "IMAGENAME eq {process_name}" | findstr /I "{process_name}"
-     ```
-   - **Unix/Mac**:
-     ```bash
-     pgrep -f "{process_name}"
-     ```
-
-3. **Check result**
-   - Process found → Verification passed, continue to Step 3
-   - Process not found → Increment attempt, wait 3 seconds, retry
-
-4. **Timeout handling**
-   - If attempt >= max_attempts → FAILED with Error Category: RUNTIME_ERROR
-   - Report: "Process verification timed out after {timeout_seconds}s - process {process_name} not found"
-
-#### Log Mode (for log-based verification)
-
-Monitor log file for success pattern:
-
-1. **Calculate max attempts**
-   - timeout_seconds = parseInt(health_timeout) || 60
-   - max_attempts = timeout_seconds / 3
-   - attempt = 0
-
-2. **Check log file for success_pattern**
-   - **Windows**:
-     ```powershell
-     Select-String -Path "{log_file}" -Pattern "{success_pattern}"
-     ```
-   - **Unix/Mac**:
-     ```bash
-     grep -m 1 "{success_pattern}" "{log_file}"
-     ```
-
-3. **Check result**
-   - Pattern found → Verification passed, continue to Step 3
-   - Pattern not found → Increment attempt, wait 3 seconds, retry
-
-4. **Timeout handling**
-   - If attempt >= max_attempts → FAILED with Error Category: RUNTIME_ERROR
-   - Report: "Log verification timed out after {timeout_seconds}s - pattern '{success_pattern}' not found in {log_file}"
-
-## Step 3: Report Startup Status
-
-Compile and report startup results:
-
-1. **Record service information**
-   - Service URL: derived from `health_url` (remove `/actuator/health` if present)
-   - Health status: UP / DOWN
-   - Startup duration: time from start to health success
-   - PID: process ID for cleanup
-
-2. **Verify application is still running**
-   - Check if process with recorded PID exists
-   - If not running → FAILED with Error Category: RUNTIME_ERROR
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
 
 # Task Completion Report
 

package/.speccrew/skills/speccrew-deploy-startup/workflow.agentflow.xml

@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="deploy-startup" status="pending" version="1.0" desc="Start application and perform health check verification">
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="platform_id" required="true" type="string" desc="Platform identifier"/>
+    <field name="start_cmd" required="true" type="string" desc="Application start command from conventions-data (e.g., java -jar target/app.jar)"/>
+    <field name="health_url" required="false" type="string" desc="Health check URL. Required for http mode."/>
+    <field name="health_timeout" required="false" type="string" default="60" desc="Health check timeout in seconds, default 60"/>
+    <field name="project_root" required="true" type="string" desc="Absolute path to the project root directory"/>
+    <field name="iteration_path" required="true" type="string" desc="Current iteration directory path"/>
+    <field name="verification_mode" required="false" type="string" default="http" desc="Verification method: http (default), process, log"/>
+    <field name="process_name" required="false" type="string" desc="Process name or pattern to check for process mode"/>
+    <field name="log_file" required="false" type="string" desc="Path to application log file for log mode"/>
+    <field name="success_pattern" required="false" type="string" desc="Regex pattern in log indicating successful startup for log mode"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="mandatory" desc="Startup execution constraints">
+    <field name="text">Application must start in background and continue running</field>
+    <field name="text">Always record and report the process PID</field>
+    <field name="text">Poll health endpoint every 5 seconds until success or timeout</field>
+    <field name="text">Timeout is configurable via health_timeout parameter</field>
+    <field name="text">Verify application process is still running after health check</field>
+  </block>
+
+  <!-- ============================================================
+       Main Processing Sequence
+       ============================================================ -->
+  <sequence id="S1" name="Application Startup" status="pending" desc="Start application, verify health, report status">
+
+    <!-- Step 1: Start Application -->
+    <block type="task" id="B1" action="run-script" desc="Execute start command in background">
+      <field name="command">${start_cmd}</field>
+      <field name="working_directory">${project_root}</field>
+      <field name="background">true</field>
+      <field name="note">On Unix: nohup {start_cmd} > app.log 2>&1 &amp;</field>
+      <field name="output" var="start_result"/>
+    </block>
+
+    <block type="task" id="B2" action="analyze" desc="Record PID for cleanup">
+      <field name="rules">Extract PID from start_result and store for later reference</field>
+      <field name="output" var="pid"/>
+    </block>
+
+    <block type="event" id="E1" action="log" level="info" desc="Log application started">
+      <field name="message">Application started with PID ${pid}</field>
+    </block>
+
+    <block type="event" id="E2" action="log" level="info" desc="Wait for initialization">
+      <field name="message">Waiting for application to initialize...</field>
+      <field name="wait_seconds">5</field>
+    </block>
+
+    <!-- Step 2: Verification (Based on Mode) -->
+    <block type="gateway" id="G0" mode="exclusive" desc="Select verification mode">
+
+      <!-- HTTP Mode (default) -->
+      <branch test="${verification_mode} == 'http' OR ${verification_mode} == null" name="HTTP Verification">
+        
+        <block type="task" id="B3" action="analyze" desc="Calculate max attempts">
+          <field name="rules">
+            - timeout_seconds = parseInt(health_timeout) || 60
+            - max_attempts = timeout_seconds / 5
+          </field>
+          <field name="output" var="http_verification_config"/>
+        </block>
+
+        <block type="loop" id="L1" over="${range(1, ${http_verification_config.max_attempts})}" as="attempt" desc="Poll health URL">
+          <block type="task" action="run-script" desc="Check health endpoint">
+            <field name="command">curl -s -o /dev/null -w "%{http_code}" ${health_url}</field>
+            <field name="output" var="http_status"/>
+          </block>
+          
+          <block type="gateway" mode="guard" desc="Check HTTP status">
+            <branch test="${http_status} == 200">
+              <block type="event" action="log" level="info" desc="Health check passed">
+                <field name="message">Health check passed with HTTP 200</field>
+                <field name="output" var="health_status" value="UP"/>
+              </block>
+            </branch>
+          </block>
+          
+          <block type="event" action="log" level="debug" desc="Wait before retry">
+            <field name="message">Attempt ${attempt}: HTTP ${http_status}, waiting 5 seconds...</field>
+            <field name="wait_seconds">5</field>
+          </block>
+        </block>
+
+        <block type="gateway" id="G1" mode="guard" desc="Check health check timeout"
+               test="${health_status} == 'UP'"
+               fail-action="stop">
+          <field name="message">Health check timed out after ${health_timeout}s</field>
+        </block>
+
+      </branch>
+
+      <!-- Process Mode -->
+      <branch test="${verification_mode} == 'process'" name="Process Verification">
+        
+        <block type="task" id="B4" action="analyze" desc="Calculate max attempts for process mode">
+          <field name="rules">
+            - timeout_seconds = parseInt(health_timeout) || 30
+            - max_attempts = timeout_seconds / 3
+          </field>
+          <field name="output" var="process_verification_config"/>
+        </block>
+
+        <block type="loop" id="L2" over="${range(1, ${process_verification_config.max_attempts})}" as="attempt" desc="Check process existence">
+          <block type="task" action="run-script" desc="Check process running">
+            <field name="command">
+              Windows: tasklist /FI "IMAGENAME eq ${process_name}" | findstr /I "${process_name}"
+              Unix/Mac: pgrep -f "${process_name}"
+            </field>
+            <field name="output" var="process_found"/>
+          </block>
+          
+          <block type="gateway" mode="guard" desc="Check process found">
+            <branch test="${process_found} == true">
+              <block type="event" action="log" level="info" desc="Process verification passed">
+                <field name="message">Process ${process_name} is running</field>
+                <field name="output" var="health_status" value="UP"/>
+              </block>
+            </branch>
+          </block>
+          
+          <block type="event" action="log" level="debug" desc="Wait before retry">
+            <field name="message">Attempt ${attempt}: Process not found, waiting 3 seconds...</field>
+            <field name="wait_seconds">3</field>
+          </block>
+        </block>
+
+        <block type="gateway" id="G2" mode="guard" desc="Check process verification timeout"
+               test="${health_status} == 'UP'"
+               fail-action="stop">
+          <field name="message">Process verification timed out after ${health_timeout}s - process ${process_name} not found</field>
+        </block>
+
+      </branch>
+
+      <!-- Log Mode -->
+      <branch test="${verification_mode} == 'log'" name="Log Verification">
+        
+        <block type="task" id="B5" action="analyze" desc="Calculate max attempts for log mode">
+          <field name="rules">
+            - timeout_seconds = parseInt(health_timeout) || 60
+            - max_attempts = timeout_seconds / 3
+          </field>
+          <field name="output" var="log_verification_config"/>
+        </block>
+
+        <block type="loop" id="L3" over="${range(1, ${log_verification_config.max_attempts})}" as="attempt" desc="Monitor log for success pattern">
+          <block type="task" action="run-script" desc="Check log for success pattern">
+            <field name="command">
+              Windows: Select-String -Path "${log_file}" -Pattern "${success_pattern}"
+              Unix/Mac: grep -m 1 "${success_pattern}" "${log_file}"
+            </field>
+            <field name="output" var="pattern_found"/>
+          </block>
+          
+          <block type="gateway" mode="guard" desc="Check pattern found">
+            <branch test="${pattern_found} == true">
+              <block type="event" action="log" level="info" desc="Log verification passed">
+                <field name="message">Success pattern '${success_pattern}' found in log</field>
+                <field name="output" var="health_status" value="UP"/>
+              </block>
+            </branch>
+          </block>
+          
+          <block type="event" action="log" level="debug" desc="Wait before retry">
+            <field name="message">Attempt ${attempt}: Pattern not found, waiting 3 seconds...</field>
+            <field name="wait_seconds">3</field>
+          </block>
+        </block>
+
+        <block type="gateway" id="G3" mode="guard" desc="Check log verification timeout"
+               test="${health_status} == 'UP'"
+               fail-action="stop">
+          <field name="message">Log verification timed out after ${health_timeout}s - pattern '${success_pattern}' not found in ${log_file}</field>
+        </block>
+
+      </branch>
+
+    </block>
+
+    <!-- Step 3: Report Startup Status -->
+    <block type="task" id="B6" action="analyze" desc="Derive service URL from health URL">
+      <field name="rules">Remove /actuator/health from health_url if present to get service URL</field>
+      <field name="output" var="service_url"/>
+    </block>
+
+    <block type="task" id="B7" action="run-script" desc="Verify process still running">
+      <field name="command">Check if process with PID ${pid} still exists</field>
+      <field name="output" var="process_running"/>
+    </block>
+
+    <block type="gateway" id="G4" mode="guard" desc="Verify process still running"
+           test="${process_running} == true"
+           fail-action="stop">
+      <field name="message">Process with PID ${pid} is no longer running. Error Category: RUNTIME_ERROR</field>
+    </block>
+
+  </sequence>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="status" value="SUCCESS" type="string" desc="Startup status"/>
+    <field name="platform_id" from="${platform_id}" type="string" desc="Platform identifier"/>
+    <field name="project_root" from="${project_root}" type="string" desc="Project root path"/>
+    <field name="service_url" from="${service_url}" type="string" desc="Service URL"/>
+    <field name="health_url" from="${health_url}" type="string" desc="Health check URL"/>
+    <field name="health_status" from="${health_status}" type="string" desc="Health status UP/DOWN"/>
+    <field name="pid" from="${pid}" type="number" desc="Process ID for cleanup"/>
+    <field name="start_command" from="${start_cmd}" type="string" desc="Start command executed"/>
+  </block>
+
+</workflow>

package/.speccrew/skills/speccrew-dev-backend/SKILL.md

@@ -20,9 +20,17 @@ tools: Bash, Edit, Write, Glob, Grep, Read
 | `iteration_id` | No | string | Current iteration identifier for progress messages |
 | `output_dir` | No | string | Output directory for task record (default: auto-derived from iteration path) |
 
-# Workflow
+## AgentFlow Definition
 
-## Absolute Constraints
+<!-- @agentflow: workflow.agentflow.xml -->
+
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
+
+---
+
+## Workflow
+
+### Absolute Constraints
 
 > **These rules apply to Task Record document generation. Violation = task failure.**