Update documentation and integrate Agent Harness

.cursorrules

@@ -0,0 +1,15 @@
+# Cursor Rules
+
+You are working in a project that follows a strict Task Documentation System.
+
+## Task System
+- **Source of Truth**: The `docs/tasks/` directory contains the state of all work.
+- **Workflow**:
+    1. Check context: `./scripts/tasks context`
+    2. Create task if needed: `./scripts/tasks create ...`
+    3. Update status: `./scripts/tasks update ...`
+- **Reference**: See `docs/tasks/GUIDE.md` for details.
+
+## Tools
+- Use `./scripts/tasks` for all task operations.
+- Use `--format json` if you need to parse output.

AGENTS.md

@@ -1,17 +1,87 @@
-# ScriptureBot Developer Guide
+# AI Agent Instructions
 
-**CURRENT STATUS: MAINTENANCE MODE**
+You are an expert Software Engineer working on this project. Your primary responsibility is to implement features and fixes while strictly adhering to the **Task Documentation System**.
 
-## Helper Scripts
-- `scripts/tasks.py`: Manage development tasks.
-  - `python3 scripts/tasks.py list`: List tasks.
-  - `python3 scripts/tasks.py create <category> <title>`: Create a task.
-  - `python3 scripts/tasks.py update <id> <status>`: Update task status.
+## Core Philosophy
+**"If it's not documented in `docs/tasks/`, it didn't happen."**
 
-## Documentation
-- `docs/architecture/`: System architecture and directory structure.
-- `docs/features/`: Feature specifications.
-- `docs/tasks/`: Active and pending tasks.
+## Workflow
+1.  **Pick a Task**: Run `python3 scripts/tasks.py next` to find the best task, `context` to see active tasks, or `list` to see pending ones.
+2.  **Plan & Document**:
+    *   **Memory Check**: Run `python3 scripts/memory.py list` (or use the Memory Skill) to recall relevant long-term information.
+    *   **Security Check**: Ask the user about specific security considerations for this task.
+    *   If starting a new task, use `scripts/tasks.py create` (or `python3 scripts/tasks.py create`) to generate a new task file.
+    *   Update the task status: `python3 scripts/tasks.py update [TASK_ID] in_progress`.
+3.  **Implement**: Write code, run tests.
+4.  **Update Documentation Loop**:
+    *   As you complete sub-tasks, check them off in the task document.
+    *   If you hit a blocker, update status to `wip_blocked` and describe the issue in the file.
+    *   Record key architectural decisions in the task document.
+    *   **Memory Update**: If you learn something valuable for the long term, use `scripts/memory.py create` to record it.
+5.  **Review & Verify**:
+    *   Once implementation is complete, update status to `review_requested`: `python3 scripts/tasks.py update [TASK_ID] review_requested`.
+    *   Ask a human or another agent to review the code.
+    *   Once approved and tested, update status to `verified`.
+6.  **Finalize**:
+    *   Update status to `completed`: `python3 scripts/tasks.py update [TASK_ID] completed`.
+    *   Record actual effort in the file.
+    *   Ensure all acceptance criteria are met.
+
+## Tools
+*   **Wrapper**: `./scripts/tasks` (Checks for Python, recommended).
+*   **Next**: `./scripts/tasks next` (Finds the best task to work on).
+*   **Create**: `./scripts/tasks create [category] "Title"`
+*   **List**: `./scripts/tasks list [--status pending]`
+*   **Context**: `./scripts/tasks context`
+*   **Update**: `./scripts/tasks update [ID] [status]`
+*   **Migrate**: `./scripts/tasks migrate` (Migrate legacy tasks to new format)
+*   **Memory**: `./scripts/memory.py [create|list|read]`
+*   **JSON Output**: Add `--format json` to any command for machine parsing.
+
+## Documentation Reference
+*   **Guide**: Read `docs/tasks/GUIDE.md` for strict formatting and process rules.
+*   **Architecture**: Refer to `docs/architecture/` for system design.
+*   **Features**: Refer to `docs/features/` for feature specifications.
+*   **Security**: Refer to `docs/security/` for risk assessments and mitigations.
+*   **Memories**: Refer to `docs/memories/` for long-term project context.
+
+## Code Style & Standards
+*   Follow the existing patterns in the codebase.
+*   Ensure all new code is covered by tests (if testing infrastructure exists).
+
+## PR Review Methodology
+When performing a PR review, follow this "Human-in-the-loop" process to ensure depth and efficiency.
+
+### 1. Preparation
+1.  **Create Task**: `python3 scripts/tasks.py create review "Review PR #<N>: <Title>"`
+2.  **Fetch Details**: Use `gh` to get the PR context.
+    *   `gh pr view <N>`
+    *   `gh pr diff <N>`
+
+### 2. Analysis & Planning (The "Review Plan")
+**Do not review line-by-line yet.** Instead, analyze the changes and document a **Review Plan** in the task file (or present it for approval).
+
+Your plan must include:
+*   **High-Level Summary**: Purpose, new APIs, breaking changes.
+*   **Dependency Check**: New libraries, maintenance status, security.
+*   **Impact Assessment**: Effect on existing code/docs.
+*   **Focus Areas**: Prioritized list of files/modules to check.
+*   **Suggested Comments**: Draft comments for specific lines.
+    *   Format: `File: <path> | Line: <N> | Comment: <suggestion>`
+    *   Tone: Friendly, suggestion-based ("Consider...", "Nit: ...").
+
+### 3. Execution
+Once the human approves the plan and comments:
+1.  **Pending Review**: Create a pending review using `gh`.
+    *   `COMMIT_SHA=$(gh pr view <N> --json headRefOid -q .headRefOid)`
+    *   `gh api repos/{owner}/{repo}/pulls/{N}/reviews -f commit_id="$COMMIT_SHA"`
+2.  **Batch Comments**: Add comments to the pending review.
+    *   `gh api repos/{owner}/{repo}/pulls/{N}/comments -f body="..." -f path="..." -f commit_id="$COMMIT_SHA" -F line=<L> -f side="RIGHT"`
+3.  **Submit**:
+    *   `gh pr review <N> --approve --body "Summary..."` (or `--request-changes`).
+
+### 4. Close Task
+*   Update task status to `completed`.
 
 ## Project Specific Instructions
 
@@ -35,3 +105,8 @@
 - **Setup**: Create a `.env` file with `TELEGRAM_ID` and `TELEGRAM_ADMIN_ID`.
 - **Run**: `go run main.go`
 - **Testing**: Use `ngrok` to tunnel webhooks or send mock HTTP requests.
+
+## Agent Interoperability
+- **Task Manager Skill**: `.claude/skills/task_manager/`
+- **Memory Skill**: `.claude/skills/memory/`
+- **Tool Definitions**: `docs/interop/tool_definitions.json`

CLAUDE.md

@@ -1,10 +1,112 @@
-# Claude Instructions
+# AI Agent Instructions
 
-See [AGENTS.md](AGENTS.md) for full context.
+You are an expert Software Engineer working on this project. Your primary responsibility is to implement features and fixes while strictly adhering to the **Task Documentation System**.
 
-## Task Management
-Use `scripts/tasks.py` to manage tasks:
-- `python3 scripts/tasks.py list`
-- `python3 scripts/tasks.py create <category> <title>`
-- `python3 scripts/tasks.py update <id> <status>`
-- `python3 scripts/tasks.py show <id>`
+## Core Philosophy
+**"If it's not documented in `docs/tasks/`, it didn't happen."**
+
+## Workflow
+1.  **Pick a Task**: Run `python3 scripts/tasks.py next` to find the best task, `context` to see active tasks, or `list` to see pending ones.
+2.  **Plan & Document**:
+    *   **Memory Check**: Run `python3 scripts/memory.py list` (or use the Memory Skill) to recall relevant long-term information.
+    *   **Security Check**: Ask the user about specific security considerations for this task.
+    *   If starting a new task, use `scripts/tasks.py create` (or `python3 scripts/tasks.py create`) to generate a new task file.
+    *   Update the task status: `python3 scripts/tasks.py update [TASK_ID] in_progress`.
+3.  **Implement**: Write code, run tests.
+4.  **Update Documentation Loop**:
+    *   As you complete sub-tasks, check them off in the task document.
+    *   If you hit a blocker, update status to `wip_blocked` and describe the issue in the file.
+    *   Record key architectural decisions in the task document.
+    *   **Memory Update**: If you learn something valuable for the long term, use `scripts/memory.py create` to record it.
+5.  **Review & Verify**:
+    *   Once implementation is complete, update status to `review_requested`: `python3 scripts/tasks.py update [TASK_ID] review_requested`.
+    *   Ask a human or another agent to review the code.
+    *   Once approved and tested, update status to `verified`.
+6.  **Finalize**:
+    *   Update status to `completed`: `python3 scripts/tasks.py update [TASK_ID] completed`.
+    *   Record actual effort in the file.
+    *   Ensure all acceptance criteria are met.
+
+## Tools
+*   **Wrapper**: `./scripts/tasks` (Checks for Python, recommended).
+*   **Next**: `./scripts/tasks next` (Finds the best task to work on).
+*   **Create**: `./scripts/tasks create [category] "Title"`
+*   **List**: `./scripts/tasks list [--status pending]`
+*   **Context**: `./scripts/tasks context`
+*   **Update**: `./scripts/tasks update [ID] [status]`
+*   **Migrate**: `./scripts/tasks migrate` (Migrate legacy tasks to new format)
+*   **Memory**: `./scripts/memory.py [create|list|read]`
+*   **JSON Output**: Add `--format json` to any command for machine parsing.
+
+## Documentation Reference
+*   **Guide**: Read `docs/tasks/GUIDE.md` for strict formatting and process rules.
+*   **Architecture**: Refer to `docs/architecture/` for system design.
+*   **Features**: Refer to `docs/features/` for feature specifications.
+*   **Security**: Refer to `docs/security/` for risk assessments and mitigations.
+*   **Memories**: Refer to `docs/memories/` for long-term project context.
+
+## Code Style & Standards
+*   Follow the existing patterns in the codebase.
+*   Ensure all new code is covered by tests (if testing infrastructure exists).
+
+## PR Review Methodology
+When performing a PR review, follow this "Human-in-the-loop" process to ensure depth and efficiency.
+
+### 1. Preparation
+1.  **Create Task**: `python3 scripts/tasks.py create review "Review PR #<N>: <Title>"`
+2.  **Fetch Details**: Use `gh` to get the PR context.
+    *   `gh pr view <N>`
+    *   `gh pr diff <N>`
+
+### 2. Analysis & Planning (The "Review Plan")
+**Do not review line-by-line yet.** Instead, analyze the changes and document a **Review Plan** in the task file (or present it for approval).
+
+Your plan must include:
+*   **High-Level Summary**: Purpose, new APIs, breaking changes.
+*   **Dependency Check**: New libraries, maintenance status, security.
+*   **Impact Assessment**: Effect on existing code/docs.
+*   **Focus Areas**: Prioritized list of files/modules to check.
+*   **Suggested Comments**: Draft comments for specific lines.
+    *   Format: `File: <path> | Line: <N> | Comment: <suggestion>`
+    *   Tone: Friendly, suggestion-based ("Consider...", "Nit: ...").
+
+### 3. Execution
+Once the human approves the plan and comments:
+1.  **Pending Review**: Create a pending review using `gh`.
+    *   `COMMIT_SHA=$(gh pr view <N> --json headRefOid -q .headRefOid)`
+    *   `gh api repos/{owner}/{repo}/pulls/{N}/reviews -f commit_id="$COMMIT_SHA"`
+2.  **Batch Comments**: Add comments to the pending review.
+    *   `gh api repos/{owner}/{repo}/pulls/{N}/comments -f body="..." -f path="..." -f commit_id="$COMMIT_SHA" -F line=<L> -f side="RIGHT"`
+3.  **Submit**:
+    *   `gh pr review <N> --approve --body "Summary..."` (or `--request-changes`).
+
+### 4. Close Task
+*   Update task status to `completed`.
+
+## Project Specific Instructions
+
+### Core Directives
+- **API First**: The Bible AI API is the primary source for data. Scraping (`pkg/app/passage.go` fallback) is deprecated and should be avoided for new features.
+- **Secrets**: Do not commit secrets. Use `pkg/secrets` to retrieve them from Environment or Google Secret Manager.
+- **Testing**: Run tests from the root using `go test ./pkg/...`.
+
+### Code Guidelines
+- **Go Version**: 1.24+
+- **Naming**:
+  - Variables: `camelCase`
+  - Functions: `PascalCase` (exported), `camelCase` (internal)
+  - Packages: `underscore_case`
+- **Structure**:
+  - `pkg/app`: Business logic.
+  - `pkg/bot`: Platform integration.
+  - `pkg/utils`: Shared utilities.
+
+### Local Development
+- **Setup**: Create a `.env` file with `TELEGRAM_ID` and `TELEGRAM_ADMIN_ID`.
+- **Run**: `go run main.go`
+- **Testing**: Use `ngrok` to tunnel webhooks or send mock HTTP requests.
+
+## Agent Interoperability
+- **Task Manager Skill**: `.claude/skills/task_manager/`
+- **Memory Skill**: `.claude/skills/memory/`
+- **Tool Definitions**: `docs/interop/tool_definitions.json`

MIGRATION.md

@@ -31,6 +31,8 @@ Update the following secrets in the GitHub Repository settings:
 *   `GCLOUD_ARTIFACT_REPOSITORY_ID`: The name of the repository created in Artifact Registry.
 *   `TELEGRAM_ID`: The Telegram Bot Token (ensure it matches the one used in the source project if preserving identity).
 *   `TELEGRAM_ADMIN_ID`: Your Telegram User ID.
+*   `BIBLE_API_URL`: The URL for the Bible API (required for new features).
+*   `BIBLE_API_KEY`: The API Key for the Bible API.
 
 ## 2. Data Migration
 

README.md

@@ -28,8 +28,8 @@ A Telegram bot to make the Bible more accessible, providing passages, search, an
     ```env
     TELEGRAM_ID=your_bot_token
     TELEGRAM_ADMIN_ID=your_user_id
-    BIBLE_API_URL=https://api.example.com (optional)
-    BIBLE_API_KEY=your_key (optional)
+    BIBLE_API_URL=https://api.example.com (Required for Q&A and Search)
+    BIBLE_API_KEY=your_key (Required for Q&A and Search)
     ```
 3.  Run the bot:
     ```bash