fix: improve documentation and template sync

Documentation:
- Improve ARCHITECTURE.md formatting and clarify task retrieval process
- Improve check_task_links.py docstring formatting

Features:
- Enhance compare.sh with better diff formatting and output
- Fix path comparison in diff_codeblock function
- Add detailed guidance for template/instance sync decisions

Author: ErikBjare

ARCHITECTURE.md

@@ -11,7 +11,6 @@ This workspace implements a forkable agent architecture, designed to be used as
 ## Search & Navigation
 
 The workspace provides several ways to search and navigate content:
-
 - Quick search:
   ```sh
   # Find files containing term
@@ -34,7 +33,6 @@ The workspace provides several ways to search and navigate content:
   - knowledge/ - Documentation
 
 ## Task System
-
 The task system is designed to help track and manage work effectively across sessions.
 
 ### Components
@@ -70,7 +68,7 @@ The task system is designed to help track and manage work effectively across ses
 ### Task Lifecycle
 
 0. **Retrieval**
-   - Retrieve context needed to plan the task
+   - Retrieve context needed to plan the task using the search tools described in "Search & Navigation" above
    - Review tasks/all/no-active-task.md if starting fresh
 
 1. **Creation**

scripts/compare.sh

@@ -30,14 +30,15 @@ AGENT_PATH=$1
 function run_codeblock() {
     # usage: run_codeblock diff "file1" "file2"
     # outputs the result of a command as a ```<command> codeblock
-    echo "Running command: $@"
+    echo
     echo "\`\`\`$@"
     eval "$@" || true
     echo "\`\`\`"
+    echo
 }
 
 function diff_codeblock() {
-    run_codeblock diff -r "$1" "$AGENT_PATH/$2"
+    run_codeblock diff -u -r "$1" "$AGENT_PATH/$1"
 }
 
 # Store diffs in a variable
@@ -62,7 +63,19 @@ if [ "$response" != "y" ]; then
   exit 0
 fi
 
-printf "%s\n" "$diffs" | gptme "We want to sync the changes in our agent with the upstream agent-template, either repo may have the best and latest changes, so you need to determine which to choose. Here are the changes we found"
+printf "%s\n" "$diffs" | gptme "We need to synchronize changes between two repositories:
+1. The template repository (source of core functionality and best practices)
+2. The agent instance (which may have improvements that should be upstreamed)
+
+For each difference found, please:
+- Analyze whether the change belongs in the template, the instance, or both
+- Consider:
+  - Is it a generic improvement that benefits all agents? (→ template)
+  - Is it instance-specific customization? (→ instance)
+  - Is it a bug fix or enhancement that works for both? (→ both)
+  - Does it maintain separation between template and instance concerns?
+
+Here are the differences found. Please analyze each and suggest appropriate synchronization:"
 
 # Exit with the status of the last command
 exit $?

scripts/precommit/check_task_links.py

@@ -27,21 +27,21 @@
 Supported Types:
     tasks:
         State Directories:
-        - tasks/new/: New tasks
-        - tasks/active/: Active tasks
-        - tasks/paused/: Paused tasks
-        - tasks/done/: Completed tasks
-        - tasks/cancelled/: Cancelled tasks
+            - tasks/new/: New tasks
+            - tasks/active/: Active tasks
+            - tasks/paused/: Paused tasks
+            - tasks/done/: Completed tasks
+            - tasks/cancelled/: Cancelled tasks
         Special Cases:
-        - no-active-task.md: Should not have any symlinks
-        - CURRENT_TASK.md: Should be a valid symlink
+            - no-active-task.md: Should not have any symlinks
+            - CURRENT_TASK.md: Should be a valid symlink
 
     tweets:
         State Directories:
-        - tweets/new/: New tweets
-        - tweets/queued/: Tweets awaiting review
-        - tweets/approved/: Tweets ready to post
-        - tweets/posted/: Published tweets
+            - tweets/new/: New tweets
+            - tweets/queued/: Tweets awaiting review
+            - tweets/approved/: Tweets ready to post
+            - tweets/posted/: Published tweets
 
 Error Reporting:
     Reports issues in format: