<patterns>
    <pattern name="get_bearings">
        <description>Commands to understand current state</description>
        <commands><![CDATA[
pwd
cat .claudesprint/project/current_issue.json
ISSUE_ID=$(cat .claudesprint/project/current_issue.json | jq -r '.issue_id')
claudesprint-tools sprint details "$ISSUE_ID"
git log --oneline -5 2>/dev/null || echo "Not a git repo"
        ]]></commands>
        <note>The full session log is automatically injected into the context. Do NOT read it manually.</note>
    </pattern>

    <pattern name="log_progress">
        <description>Append structured log entries to session log</description>
        <commands><![CDATA[
echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] STEP: <from> -> <to>" >> .claudesprint/project/current_issue.log
echo "  <summary>" >> .claudesprint/project/current_issue.log
        ]]></commands>
    </pattern>

    <pattern name="update_current_issue">
        <description>Use CLI tools for state updates (see state_management section)</description>
        <note>All updates MUST go through claudesprint-tools CLI for schema validation.</note>
    </pattern>
</patterns>

<state_management>
    <rule>NEVER write to current_issue.json directly using bash/cat/jq.</rule>
    <rule>ALWAYS use the provided CLI tools:</rule>
    <rule priority="critical">Do NOT set the step field manually. Step transitions are handled automatically by the workflow engine based on routing rules and skip gates (require_testing, require_browser_qa).</rule>

    <command name="update-fields">
        <syntax>claudesprint-tools issue update [--goal="..."] [--next-action="..."]</syntax>
        <example>claudesprint-tools issue update --next-action="Fix validation bug"</example>
    </command>

    <command name="record-change">
        <syntax>claudesprint-tools issue change &lt;path&gt; &lt;summary&gt;</syntax>
        <example>claudesprint-tools issue change src/auth.py "Added login validation"</example>
    </command>

    <command name="record-failure">
        <syntax>claudesprint-tools issue failure &lt;message&gt;</syntax>
        <example>claudesprint-tools issue failure "AssertionError: expected 200"</example>
    </command>

    <command name="clear-failures">
        <syntax>claudesprint-tools issue clear-failures</syntax>
        <example>claudesprint-tools issue clear-failures</example>
        <note>Use after fixing issues to clear failure state and reset retry count.</note>
    </command>

    <forbidden>
        <action>cat > .claudesprint/...</action>
        <action>jq ... > tmp && mv tmp ...</action>
        <action>echo '{"..."}' > current_issue.json</action>
        <action>claudesprint-tools issue step (step transitions are automatic)</action>
    </forbidden>
</state_management>

<termination_tags>
    <description>Routing signal tags for step completion. Use ONLY these tags to indicate step outcome.</description>
    <tag name="pass">Step succeeded</tag>
    <tag name="fail">Step failed (generic)</tag>
    <tag name="fail_code">Step failed due to code bug</tag>
    <tag name="fail_test">Step failed due to test bug</tag>
    <tag name="skip">Step skipped (not applicable)</tag>
    <tag name="issues">Issues found (code review)</tag>
    <tag name="test_fixed">Test was fixed, ready to re-run</tag>
    <tag name="code_wrong">Code needs fixing, not the test</tag>
    <format><![CDATA[<routing_signal>value</routing_signal>]]></format>
    <important>Do NOT use <status> tags - use <routing_signal> exclusively.</important>
</termination_tags>

<session_rules>
    <rule priority="1">ONLY use current_issue.json + sprint.json as context - no other context sources</rule>
    <rule priority="2">Fail fast if required fields missing - stop and report</rule>
    <rule priority="3">Execute one step completely, then update current_issue.json</rule>
    <rule priority="4">Log progress to current_issue.log using the log_progress pattern</rule>
    <rule priority="5">Validate before exit - run claudesprint validate when applicable</rule>
</session_rules>

<critical_rules>
    <section name="commit">
        <rule>Do NOT commit unless: implementation complete, tests pass, code review clean</rule>
        <rule>Use explicit file staging (not git add -A or git add .)</rule>
    </section>
    <section name="sprint">
        <rule>sprint.json issues are immutable contracts</rule>
        <rule>Only change status and history fields during implementation</rule>
    </section>
    <section name="scope">
        <rule>ONE issue per workflow cycle</rule>
        <rule>Exit after completing one issue for fresh context</rule>
    </section>
</critical_rules>

<implementation_guidelines>
    <do>
        <item>Exactly what acceptance criteria specify</item>
        <item>Error handling for edge cases</item>
        <item>Tests that verify acceptance criteria</item>
    </do>
    <dont>
        <item>Features not in acceptance criteria</item>
        <item>Optimizations not requested</item>
        <item>Refactoring unrelated code</item>
        <item>Extra configurability beyond requirements</item>
        <item>Unnecessary documentation</item>
    </dont>
</implementation_guidelines>

<valid_steps>
    <!-- Note: select-issue is handled by SprintEngine, not IssueEngine -->
    <step>read-docs</step>
    <step>implement</step>
    <step>write-tests</step>
    <step>run-tests</step>
    <step>fix-tests</step>
    <step>browser-validation</step>
    <step>code-review</step>
    <step>fix-code-review-issues</step>
    <step>update-docs</step>
    <step>stage-changes</step>
    <step>commit-changes</step>
    <step>complete-issue</step>
</valid_steps>
