fix: upstream improvements from bob (#12)

* fix: upstream improvements from bob

* Apply suggestions from code review

* Apply suggestions from code review

* include TOOLS.md in fork

* almost there

* almost...

Author: ErikBjare

ARCHITECTURE.md

@@ -8,97 +8,86 @@ This workspace implements a forkable agent architecture, designed to be used as
 - Forking process: See [`knowledge/agent-forking.md`](./knowledge/agent-forking.md)
 - Workspace structure: See [`knowledge/forking-workspace.md`](./knowledge/forking-workspace.md)
 
-## Search & Navigation
-
-The workspace provides several ways to search and navigate content:
-- Quick search:
-  ```sh
-  # Find files containing term
-  git grep -li <query>
-
-  # Show matching lines
-  git grep -i <query>
-  ```
-- Detailed search with context:
-  ```sh
-  # Show matching lines
-  ./scripts/search.sh "<query>"
-
-  # Show with context
-  ./scripts/search.sh "<query>" 1
-  ```
-- Common locations:
-  - tasks/all/ - Task details
-  - journal/ - Daily updates
-  - knowledge/ - Documentation
+## Tools
+
+For a information about tools used in this workspace, see [`TOOLS.md`](./TOOLS.md).
 
 ## Task System
-The task system is designed to help track and manage work effectively across sessions.
+
+The task system is designed to help Bob track and manage work effectively across sessions.
 
 ### Components
 
-1. **TASKS.md**
+1. [**`TASKS.md`**](./TASKS.md)
    - Main task registry
    - Contains all tasks categorized by area
    - Each task has a clear status indicator
-   - Links to task files in tasks/all/
-
+   - Links to task files in `tasks/`
 
 2. **Task Files**
-   - All task files stored in `tasks/all/` as single source of truth
+   - All task files stored in [`tasks/`](./tasks) as single source of truth
    - Task state managed via symlinks in state directories:
      - `tasks/new/`: Symlinks to new tasks
      - `tasks/active/`: Symlinks to tasks being worked on
      - `tasks/paused/`: Symlinks to temporarily paused tasks
      - `tasks/done/`: Symlinks to completed tasks
      - `tasks/cancelled/`: Symlinks to cancelled tasks
-   - Never modify task files directly in state directories, always modify in tasks/all/
+   - Never modify task files directly in state directories, always modify in `tasks/`
 
-3. **CURRENT_TASK.md**
-   - Always a symlink, never modify directly
-   - Points to active task in tasks/all/ when task is active
-   - Points to tasks/all/no-active-task.md when no task is active
-   - Updated using ln -sf command when switching tasks
-
-4. **Journal Entries**
-   - Daily progress logs in `./journal/`
+3. **Journal Entries**
+   - Daily progress logs in [`journal/`](./journal)
    - Each entry documents work done on tasks
    - Includes reflections and next steps
 
 ### Task Lifecycle
 
 0. **Retrieval**
-   - 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
+   - Retrieve context needed to plan the task
+      - Quick search:
+        ```sh
+        # Find files containing term
+        git grep -li <query>
+
+        # Show matching lines
+        git grep -i <query>
+        ```
+      - Detailed search with context:
+        ```sh
+        # Show matching lines
+        ./scripts/search.sh "<query>"
+
+        # Show with context
+        ./scripts/search.sh "<query>" 1
+        ```
+      - Common locations:
+        - `tasks/` - Task details
+        - `journal/` - Daily updates
+        - `knowledge/` - Documentation
 
 1. **Creation**
-   - Create new task file in tasks/all/
-   - Add symlink in tasks/new/: `ln -s ../all/taskname.md tasks/new/`
-   - Add to TASKS.md with 🆕 status
-   - CURRENT_TASK.md remains linked to no-active-task.md
+   - Create new task file in `tasks/`
+   - Add symlink in `tasks/new/`: `ln -s ../taskname.md tasks/new/`
+   - Add to `TASKS.md` with 🆕 status
 
 2. **Activation**
-   - Move symlink from new/ to active/: `mv tasks/new/taskname.md tasks/active/`
-   - Update CURRENT_TASK.md symlink: `ln -sf tasks/all/taskname.md CURRENT_TASK.md`
-   - Update status in TASKS.md to 🏃
+   - Move symlink from `new/` to `active/`: `mv tasks/new/taskname.md tasks/active/`
+   - Update status in `TASKS.md` to 🏃
    - Create journal entry about starting task
 
 3. **Progress Tracking**
    - Daily updates in journal entries
-   - Status updates in TASKS.md
+   - Status updates in `TASKS.md`
    - Subtask completion tracking
-   - All edits made to file in tasks/all/
+   - All edits made to file in `tasks/`
 
 4. **Completion/Cancellation**
-   - Update status in TASKS.md to ✅ or ❌
+   - Update status in `TASKS.md` to ✅ or ❌
    - Move symlink to done/ or cancelled/: `mv tasks/active/taskname.md tasks/done/`
-   - Reset CURRENT_TASK.md to no-active-task.md: `ln -sf tasks/all/no-active-task.md CURRENT_TASK.md`
    - Final journal entry documenting outcomes
 
 5. **Pausing**
-   - Move symlink from active/ to paused/: `mv tasks/active/taskname.md tasks/paused/`
-   - Reset CURRENT_TASK.md to no-active-task.md: `ln -sf tasks/all/no-active-task.md CURRENT_TASK.md`
-   - Update status in TASKS.md to ⏸️
+   - Move symlink from `active/` to `paused/`: `mv tasks/active/taskname.md tasks/paused/`
+   - Update status in `TASKS.md` to ⏸️
    - Document progress in journal
 
 ### Status Indicators
@@ -112,53 +101,50 @@ The task system is designed to help track and manage work effectively across ses
 ### Best Practices
 
 1. **File Management**
-   - Always treat tasks/all/ as single source of truth
+   - Always treat `tasks/` as single source of truth
    - Never modify files directly in state directories
    - Use proper symlink commands for state transitions
    - Verify symlinks after state changes
-   - Keep no-active-task.md as template for inactive state
 
-2. **Document Linking**
-   - Always link to referenced tasks and documents
-   - Use relative paths from repository root when possible
-   - Common links to include:
-     - Tasks mentioned in journal entries
-     - Related tasks in task descriptions
-     - People mentioned in any document
-     - Projects being discussed
-     - Knowledge base articles
-   - Use descriptive link text that makes sense out of context
-
-3. **Task Creation**
+2. **Task Creation**
    - Use clear, specific titles
    - Break down into manageable subtasks
    - Include success criteria
    - Link related resources
-   - Create files in tasks/all/ first, then symlink
+   - Create files in `tasks/` first, then symlink
 
 3. **Progress Updates**
-   - Daily journal entries
-   - Regular status updates in TASKS.md
+   - Regular status updates in `TASKS.md`
    - Document blockers/issues
    - Track dependencies
-   - All edits made to files in tasks/all/
+   - All edits made to files in `tasks/`
 
 4. **Documentation**
-   - Never modify CURRENT_TASK.md directly (it's a symlink)
    - Cross-reference related tasks using paths relative to repository root
    - Document decisions and rationale
    - Link to relevant documents and resources
    - Update knowledge base as needed
 
+5. **Linking**
+   - Always link to referenced resources (tasks, knowledge, URLs)
+   - Use relative paths from repository root when possible
+   - Common links to include:
+     - Tasks mentioned in journal entries
+     - Related tasks in task descriptions
+     - People mentioned in any document
+     - Projects being discussed
+     - Knowledge base articles
+   - Use descriptive link text that makes sense out of context
 
 ## Journal System
 
 The journal system provides a daily log of activities, thoughts, and progress.
 
 ### Structure
 - One file per day: `YYYY-MM-DD.md`
-- Located in `./journal/` directory
+- Located in [`journal/`](./journal) directory
 - Entries are to be appended, not overwritten
+- Historical entries are not to be modified
 - Contains:
   - Task progress updates
   - Decisions and rationale
@@ -170,7 +156,7 @@ The journal system provides a daily log of activities, thoughts, and progress.
 The knowledge base stores long-term information and documentation.
 
 ### Structure
-- Located in `./knowledge/`
+- Located in [`knowledge/`](./knowledge)
 - Organized by topic/domain
 - Includes:
   - Technical documentation
@@ -180,10 +166,10 @@ The knowledge base stores long-term information and documentation.
 
 ## People Directory
 
-The people directory stores information about individuals the agent interacts with.
+The people directory stores information about individuals Bob interacts with.
 
 ### Structure
-- Located in `./people/`
+- Located in [`people/`](./people)
 - Contains:
   - Individual profiles in Markdown format
   - Templates for consistent profile creation

CURRENT_TASK.md

@@ -1,5 +1,6 @@
 .PHONY: precommit format
 
+# to fix `git grep` for users with PAGER set
 PAGER=cat
 
 install:

Makefile

@@ -48,7 +48,6 @@ Then simply follow the instructions in the output.
 ## Workspace Structure
 
  - gptme-agent keeps track of tasks in [`TASKS.md`](./TASKS.md)
- - gptme-agent writes about the current task in [`CURRENT_TASK.md`](./CURRENT_TASK.md)
  - gptme-agent keeps a journal in [`./journal/`](./journal/)
  - gptme-agent keeps a knowledge base in [`./knowledge/`](./knowledge/)
  - gptme-agent maintains profiles of people in [`./people/`](./people/)

README.md

@@ -3,7 +3,7 @@
 Active tasks and their current status.
 
 ## Current Task
-- 🏃 [Initial Agent Setup](./tasks/all/initial-agent-setup.md)
+- 🏃 [Initial Agent Setup](./tasks/initial-agent-setup.md)
 
 ## System Development
 - 🏃 Complete initial setup

TASKS.md

@@ -0,0 +1,25 @@
+# Tools
+
+Bob has the tools enabled in gptme, and can in addition use the following tools in his workspace.
+
+
+## Search & Navigation
+
+The workspace provides several ways to search and navigate content:
+
+- Quick search:
+  ```sh
+  # Find files containing term
+  git grep -li <query>
+
+  # Show matching lines
+  git grep -i <query>
+  ```
+- Common locations:
+  - tasks/ - Task details
+  - journal/ - Daily updates
+  - knowledge/ - Documentation
+
+It can often be a good idea to start with a quick search to get an overview, and then use the detailed search to get more context.
+
+Avoid direct use of `grep` or `find` commands, as they may not respect `.gitignore` rules.

TOOLS.md

@@ -40,7 +40,7 @@ echo -e "\nCreating new agent '$NEW_AGENT' in directory '$TARGET_DIR'..."
 
 # Create core directory structure
 echo "Creating directory structure..."
-mkdir -p "${TARGET_DIR}"/{journal,tasks/{all,active,done,new,paused,cancelled,templates},projects,knowledge,people/templates,scripts/precommit}
+mkdir -p "${TARGET_DIR}"/{journal,tasks/{active,done,new,paused,cancelled,templates},projects,knowledge,people/templates,scripts/precommit}
 
 # Copy core files and directories
 echo "Copying core files..."
@@ -76,6 +76,7 @@ function copy_file() {
 copy_file README.md
 cp "${SOURCE_DIR}/Makefile" "${TARGET_DIR}/Makefile"  # copy without replacing NAME_TEMPLATE
 copy_file ARCHITECTURE.md
+copy_file TOOLS.md
 copy_file .pre-commit-config.yaml
 copy_file scripts
 copy_file run.sh
@@ -88,14 +89,10 @@ copy_file knowledge/forking-workspace.md
 # Copy template
 copy_file */templates/*.md
 
-# Initialize tasks
-echo "# No Active Task" > "${TARGET_DIR}/tasks/all/no-active-task.md"
-
 # Initial setup task from template
 copy_file tasks/templates/initial-agent-setup.md
-cp "${SOURCE_DIR}/tasks/templates/initial-agent-setup.md" "${TARGET_DIR}/tasks/all/"
-ln -sf "../all/initial-agent-setup.md" "${TARGET_DIR}/tasks/active/"
-ln -sf "./tasks/all/initial-agent-setup.md" "${TARGET_DIR}/CURRENT_TASK.md"
+cp "${SOURCE_DIR}/tasks/templates/initial-agent-setup.md" "${TARGET_DIR}/tasks/"
+ln -sf "../initial-agent-setup.md" "${TARGET_DIR}/tasks/active/"
 
 # Create projects README
 cat > "${TARGET_DIR}/projects/README.md" << EOL
@@ -131,7 +128,7 @@ cat > "${TARGET_DIR}/TASKS.md" << EOL
 Active tasks and their current status.
 
 ## Current Task
-- 🏃 [Initial Agent Setup](./tasks/all/initial-agent-setup.md)
+- 🏃 [Initial Agent Setup](./tasks/initial-agent-setup.md)
 
 ## System Development
 - 🏃 Complete initial setup
@@ -146,7 +143,6 @@ files = [
   "ARCHITECTURE.md",
   "ABOUT.md",
   "TASKS.md",
-  "CURRENT_TASK.md",
   "projects/README.md",
   "gptme.toml"
 ]

fork.sh

@@ -3,7 +3,6 @@ files = [
   "ARCHITECTURE.md",
   "ABOUT.md",
   "TASKS.md",
-  "CURRENT_TASK.md",
   "projects/README.md",
   "gptme.toml"
 ]

gptme.toml

@@ -9,11 +9,10 @@ This document describes what remains and what gets cleared when forking an agent
 ├── README.md               # Overview (template remains, content updated)
 ├── ABOUT.md               # Agent identity (cleared and customized)
 ├── ARCHITECTURE.md        # System architecture (remains)
-├── CURRENT_TASK.md        # Symlink to active task (reset to no-active-task.md)
+├── TOOLS.md               # Tool integrations (remains)
 ├── gptme.toml            # Config file (template remains, paths updated)
 ├── tasks/                # Task management (structure remains, content cleared)
 │   ├── active/          # Current tasks
-│   ├── all/            # Source of truth
 │   ├── done/           # Completed tasks
 │   └── ...             # Other task states
 ├── journal/             # Daily logs (cleared)