docs: update all references from Python tools to TypeScript/YAML

Author: apiad

.opencode/agents/build.md

@@ -3,17 +3,17 @@ description: Expert project manager that orchestrates TCR (Test-Commit-Revert) c
 mode: primary
 ---
 
-You are an expert project manager. Your goal is to manage the project's roadmap in `TASKS.md` EXCLUSIVELY via the `task` tool.
+You are an expert project manager. Your goal is to manage the project's roadmap in `tasks.yaml` EXCLUSIVELY via the `task` tool.
 
-**CRITICAL: NEVER modify `TASKS.md` directly with file-editing tools. You MUST use the task tool.**
+**CRITICAL: NEVER modify `tasks.yaml` directly with file-editing tools. You MUST use the task tool.**
 
 Depending on the user's intent or arguments, perform one of the following actions:
 
 ### **Action: Create**
 Add a new task using the task tool.
 1. Determine an appropriate `label`, `description`, `category`, and `complexity` for the task.
 2. Use the task tool with `add` action to create the task.
-3. Verify the update by reading the new `TASKS.md`.
+3. Verify the update by reading the new `tasks.yaml`.
 
 ### **Action: Work**
 Implement a task using a strict, agent-delegated Test-Commit-Revert (TCR) protocol on a feature branch.
@@ -51,13 +51,13 @@ NOTE: The builder subagent is specialized for grunt coding. Make sure to give it
 
 ### **Action: Report**
 Produce a strategic report of current tasks.
-1. Read `TASKS.md` and list all active tasks (Todo or In Progress).
+1. Read `tasks.yaml` and list all active tasks (Todo or In Progress).
 2. For each, provide a brief assessment of its **Feasibility** and **Strategic Value**.
 3. Sort the list by high value and feasibility, suggesting 2-3 top priorities.
 
 ### **Action: Update**
-Synchronize `TASKS.md` with the project's progress.
-1. Read `TASKS.md`, `CHANGELOG.md`, and recent `journal/` entries.
+Synchronize `tasks.yaml` with the project's progress.
+1. Read `tasks.yaml`, `CHANGELOG.md`, and recent `journal/` entries.
 2. Analyze uncommitted changes and conversation context.
 3. Use the task tool (`start`, `cancel`, `archive`) to update task statuses as appropriate.
 4. If a task requires a linked plan, use the task tool's `attach-plan` action.

.opencode/agents/plan.md

@@ -34,9 +34,9 @@ Follow these phases strictly:
 4. Use a descriptive, kebab-case filename (e.g., `plans/implement-auth.md`).
 5. Notify the user that the plan has been saved.
 
-### Phase 4: Task Synchronization (TASKS.md)
-1. Read the current `TASKS.md` file to understand the project roadmap.
-2. Use `ask_user` to ask the user if they want to link this plan to `TASKS.md`. Provide options if they are relevant:
+### Phase 4: Task Synchronization (tasks.yaml)
+1. Read the current `tasks.yaml` file to understand the project roadmap.
+2. Use `ask_user` to ask the user if they want to link this plan to `tasks.yaml`. Provide options if they are relevant:
    - "Add as a new task"
    - "Update an existing task"
    - "Skip"

.opencode/agents/write.md

@@ -9,7 +9,7 @@ You are an expert technical writer. You produce and refine high-quality technica
 
 ### Phase 1: Context & Mode Selection
 1. **Identify Topic/File:** Determine the topic the user wants to draft or the existing file they want to refine.
-2. **Search Context:** Search for existing context in `research/`, `plans/`, `TASKS.md`, and `journal/`. Use `list_directory` and `read_file`.
+2. **Search Context:** Search for existing context in `research/`, `plans/`, `tasks.yaml`, and `journal/`. Use `list_directory` and `read_file`.
 3. **Check for Review:** Search for a corresponding `<filename>.review.md` file for the target file.
 4. **Mode Branching:**
    - **Refinement Mode:** If a `.review.md` file exists, propose entering **Refinement Mode** to apply the suggested changes.

.opencode/commands/onboard.md

@@ -6,7 +6,7 @@ agent: query
 Senior engineer onboarding a new developer. Provide a concise, high-signal orientation using direct observation.
 
 **Phase 1: Direct Discovery**
-1. **Read Core Docs:** Read `README.md`, `TASKS.md`, and the 2 most recent entries in `journal/`.
+1. **Read Core Docs:** Read `README.md`, `tasks.yaml`, and the 2 most recent entries in `journal/`.
 2. **Map Structure:** List files the root and key directories (e.g., `src/`) to understand the layout.
 3. **Explore Context:**
    - If a `docs/` directory exists, read its contents to understand deeper project context.
@@ -19,7 +19,7 @@ Produce a professional, welcoming summary:
 - **Architecture & Layout:** High-level mapping of directories and core technologies.
 - **Workflow & Standards:** How to run, test, and commit (from README/makefile).
 - **Deep Dive (if available):** Key insights from `docs/` or source code analysis.
-- **Current State:** Recent activity and active tasks (from journal/TASKS.md).
+- **Current State:** Recent activity and active tasks (from journal/tasks.yaml).
 - **First Steps:** 2-3 specific files or commands to start with.
 
 Synthesize the report directly from your findings.

README.md

@@ -63,13 +63,13 @@ The `.opencode/commands/` directory defines specialized workflows that automate
     *   **Phase 1 (Clarification):** The agent interviews you to resolve ambiguities before planning.
     *   **Phase 2 (Agentic Analysis):** A specialized `planner` subagent scans the codebase and generates a detailed technical strategy.
     *   **Phase 3 (Artifact Generation):** A persistent Markdown plan is saved in `plans/` (e.g., `plans/feature-x.md`).
-    *   **Phase 4 (Synchronization):** The plan is optionally linked to `TASKS.md` and can be synchronized with GitHub issues.
+    *   **Phase 4 (Synchronization):** The plan is optionally linked to `tasks.yaml` and can be synchronized with GitHub issues.
 *   **`/onboard`**: Summarizes the project's architecture, standards, and current state to quickly orient a new developer (or the agent itself).
 
 ### 🏗️ Phase 2: Development & Execution
 *   **`/issues`**: Your gateway to GitHub integration. It allows you to list, create, or update issues. Use `/issues work <number>` to transition an issue directly into a detailed research and planning mode.
 *   **`/debug`**: Activates a specialized `debugger` subagent to perform forensic root-cause analysis (RCA). It analyzes error logs, traces code execution, and generates structured reports to pinpoint bugs.
-*   **`/task`**: Manages the project roadmap in `TASKS.md`. Use it to `create` new tasks, `work` on existing ones (marks as In Progress), `report` on priorities, or `update` the roadmap.
+*   **`/task`**: Manages the project roadmap in `tasks.yaml`. Use it to `add` new tasks, `start` work on existing ones, `archive` completed ones, or `list` priorities.
 *   **`/scaffold`**: Initializes new project structures from scratch using modern, standard tooling (Python/uv, TS/npm, Rust/cargo, etc.) and sets up a compatible `makefile`.
 
 ### 🧹 Phase 3: Content Generation, Maintenance & Documentation
@@ -90,7 +90,7 @@ This framework shines when you combine these commands into cohesive workflows:
 ### 1️⃣ Feature Development Workflow
 1.  **Discover:** Run `/research` to understand the domain or library.
 2.  **Plan:** Use `/plan` to turn requirements into a technical roadmap in `plans/`.
-3.  **Track:** Link the plan to `TASKS.md` using `/plan`'s built-in sync.
+3.  **Track:** Link the plan to `tasks.yaml` using `/task attach-plan`.
 4.  **Implement:** Use `/task work` to mark progress and begin coding.
 5.  **Refine:** Run `/document` to ensure your changes are well-documented.
 6.  **Ship:** Use `/commit` for clean history and `/release` for a new version tag.
@@ -110,9 +110,9 @@ This framework shines when you combine these commands into cohesive workflows:
 
 The framework uses a git pre-commit hook to enforce engineering standards:
 
-*   **`git-precommit.py` (Git Hook)**: Enforces daily journaling and timestamp-based validation before any code changes are finalized.
-*   **`journal.py` (Script)**: The dedicated utility for correctly formatting and appending new journal entries.
-*   **`task.py` (Script)**: Manages the project roadmap in `TASKS.md`.
+*   **`pre-commit.py` (Git Hook)**: Enforces daily journaling and timestamp-based validation before any code changes are finalized.
+*   **`journal.ts` (Tool)**: The dedicated tool for correctly formatting and appending new journal entries.
+*   **`task.ts` (Tool)**: Manages the project roadmap in `tasks.yaml`.
 
 Install hooks with: `make install-hooks`
 

docs/deploy.md

@@ -17,7 +17,7 @@ Running `install.sh` in an empty directory will:
 - Initialize a fresh Git repository.
 - Extract the core `.opencode/` framework and configuration files.
 - Create the standard project structure (`journal/`, `plans/`, `research/`, `drafts/`).
-- Initialize baseline files (`README.md`, `CHANGELOG.md`, `TASKS.md`, `makefile`).
+- Initialize baseline files (`README.md`, `CHANGELOG.md`, `tasks.yaml`, `makefile`).
 - Perform an initial "feat" commit.
 
 ### 2. Existing Project (Integration & Updates)
@@ -29,7 +29,6 @@ If run inside an existing project, the script performs a **Surgical Update**:
 - **Protection:** Explicitly preserves user configurations in **Protected Files**:
     - `opencode.json`
     - `.opencode/style-guide.md`
-- **Intelligent GEMINI.md Merge:** Preserves your custom content in the `## Project Notes` section of `GEMINI.md` while updating the core mandates above it.
 - **Confirm:** Presents a detailed summary of which files will be **created**, **updated**, or **protected** and waits for your approval.
 - **Integrate:** Adds missing directory structures (`journal/`, `plans/`, etc.) if they don't exist.
 - **Commit:** Automatically creates a descriptive `chore` commit marking the update.
@@ -52,7 +51,7 @@ After installation, you **must** link the framework's hooks to your git reposito
 make install-hooks
 ```
 
-This target creates a symbolic link from `.opencode/tools/git-precommit.py` to `.git/hooks/pre-commit`, enabling the automated journal and validation checks.
+This target creates a symbolic link from `.opencode/tools/pre-commit.py` to `.git/hooks/pre-commit`, enabling the automated journal and validation checks.
 
 ## 🚢 Getting Started
 
@@ -68,7 +67,7 @@ gemini /onboard
 
 ### 2. Initialize the Roadmap
 
-Check the current `TASKS.md` file and use the `/task` command to define your project's initial goals.
+Check the current `tasks.yaml` file and use the `/task` command to define your project's initial goals.
 
 ### 3. Start a New Feature
 

docs/design.md

@@ -70,19 +70,26 @@ The `/task work` command enforces a high-discipline development lifecycle throug
 
 ## 📝 Procedural Task Management
 
-The `TASKS.md` file is managed exclusively via `.opencode/tools/task.py`:
+The `tasks.yaml` file is managed exclusively via the `task` tool:
 
 - **Single source of truth** for project roadmap
 - **State lifecycle:** `add` (Todo) → `start` (In Progress) → `archive` (Done)
-- **Never edit `TASKS.md` by hand** — always use the task script
+- **Never edit `tasks.yaml` by hand** — always use the task tool
+
+!!! warning "Migrating from TASKS.md"
+    If you have an existing `TASKS.md` file, instruct the model to migrate it:
+    ```
+    /task please migrate from @TASKS
+    ```
 
 ### Usage
 
 ```bash
-python .opencode/tools/task.py --help
-python .opencode/tools/task.py add --label "Feature X" --description "..."
-python .opencode/tools/task.py start --task-id G.1
-python .opencode/tools/task.py archive --task-id G.1
+task list                    # Show all tasks
+task add --label "Feature X" --description "..."
+task start --task-id G.1
+task archive --task-id G.1
+task attach-plan --task-id G.1 --plan-path plans/my-plan.md
 ```
 
 ## 🔍 Scientific Debugging (`/debug`)
@@ -98,7 +105,7 @@ The `/debug` command implements a principled approach to problem-solving:
 
 The framework uses a timestamp-based git hook to enforce journaling:
 
-- **Hook location:** `.opencode/tools/git-precommit.py`
+- **Hook location:** `.opencode/tools/pre-commit.py`
 - **Install:** `make install-hooks`
 - **Rule:** Journal entry timestamp must be newer than file modifications
 
@@ -109,14 +116,14 @@ The framework uses a timestamp-based git hook to enforce journaling:
 ├── agents/          # Primary agent definitions
 │   └── subagents/  # Specialized subagents
 ├── commands/        # High-level commands
-├── tools/           # Utilities (task.py, journal.py, git-precommit.py)
+├── tools/           # Utilities (TypeScript tools: task.ts, journal.ts, pre-commit.py)
 └── style-guide.md   # Prose style rules
 
 plans/               # Saved execution plans
-journal/             # Daily journal entries (YYYY-MM-DD.md)
+journal/             # Daily journal entries (YYYY-MM-DD.yaml)
 research/           # Research artifacts
 drafts/             # Content drafts
-TASKS.md            # Project roadmap (managed by task.py)
+tasks.yaml          # Project roadmap (managed by task tool)
 ```
 
 ## ⚙️ Technology Stack

docs/develop.md

@@ -23,21 +23,21 @@ Before proposing a change, you must gather context and identify risks. Use the s
 
 ### 2. Strategic Planning (The Bridge)
 
-A feature or fix is not considered "active" until a persistent Markdown plan has been created in the `plans/` directory. Use the `/plan` command to synthesize the artifacts generated in Phase 1 into an actionable strategy, and synchronize it with `TASKS.md`.
+A feature or fix is not considered "active" until a persistent Markdown plan has been created in the `plans/` directory. Use the `/plan` command to synthesize the artifacts generated in Phase 1 into an actionable strategy, and synchronize it with `tasks.yaml`.
 
 ### 3. Execution & Validation (Side-Effects)
 
 Once a plan is approved, you move to execution. This is the **only** phase where files are modified.
 
 #### For Code: The TCR Protocol
 The `/task` command is the primary tool for repository execution:
-- **`/task create`**: Adds a new task using the `task.py` script.
-- **`/task work on ...`**: Implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code. The orchestrator automatically uses `task.py` to mark the task as in-progress.
-- **`/task report`**: Provides a summary of the roadmap and current priorities.
-- **`/task update`**: Updates the status or plan-path of an existing task via the script.
+- **`task add`**: Adds a new task using the `task` tool.
+- **`task start --task-id X`**: Marks a task as in-progress.
+- **`task list`**: Provides a summary of the roadmap and current priorities.
+- **`task archive --task-id X`**: Marks a task as done.
 
 **CLI-First Roadmap Discipline:**
-The project roadmap (`TASKS.md`) must **never** be edited by hand. All task operations must be performed via the `.opencode/tools/task.py` script or the corresponding `/task` actions. This ensures structural integrity and a verifiable audit trail.
+The project roadmap (`tasks.yaml`) must **never** be edited by hand. All task operations must be performed via the `task` tool or the corresponding `/task` actions. This ensures structural integrity and a verifiable audit trail.
 
 #### **The TCR Loop (Work Action)**
 
@@ -65,7 +65,7 @@ When a bug is detected, the `/debug` command enforces a structured, scientific i
 Before merging or committing any final change, the work **must** be documented in the daily journal. This is enforced by a **timestamp-based git hook**. Use the following tool to satisfy the requirement:
 
 ```bash
-python3 .opencode/tools/journal.py 'one-line description of the work'
+journal add "one-line description of the work"
 ```
 
 Failure to do this will block your commit or turn execution.
@@ -81,7 +81,10 @@ Failure to do this will block your commit or turn execution.
 
 ## 🧠 Codifying Knowledge with Skills
 
-The `/learn` command is the primary tool for expanding the project's long-term memory. When mastering a new technology, follow this workflow:
+!!! warning "[PENDING IMPLEMENTATION]"
+    The `/learn` command for expanding the project's long-term memory is **not yet implemented**. This section describes the planned feature.
+
+The planned `/learn` command will be the primary tool for expanding the project's long-term memory. When mastering a new technology, follow this workflow:
 
 ### 1. Grounded Learning Lifecycle
 The agent follows a 4-phase process: **Audit** (environment check), **Strategic Mapping** (learning objectives), **Execution** (real-world experimentation), and **Codification**.

docs/index.md

@@ -40,7 +40,7 @@ curl -fsSL https://apiad.github.io/starter/install.sh | bash
 ```
 
 !!! success "Next Steps"
-    After installation, run `gemini /onboard` to get an overview of the repository and start your first session.
+    After installation, run `opencode /onboard` to get an overview of the repository and start your first session.
 
 ## 🛠️ Key Capabilities
 
@@ -51,14 +51,14 @@ curl -fsSL https://apiad.github.io/starter/install.sh | bash
 - **Architectural Planning:** Use `/plan` to generate persistent, actionable strategies.
 - **Forensic Debugging:** Use `/debug` for root-cause analysis without immediate (and potentially incorrect) fixes.
 - **Automated Documentation:** Use `/document` to keep the documentation synchronized with the evolving codebase.
-- **Procedural Roadmap Management:** Use `/task` and the `.opencode/tools/task.py` utility to maintain a structured, machine-managed project roadmap in `TASKS.md`.
+- **Procedural Roadmap Management:** Use `/task` and the `task` tool to maintain a structured, machine-managed project roadmap in `tasks.yaml`.
 
 ## 🔄 Project Lifecycle
 
 1.  **Onboarding:** Run `/onboard` to get a high-signal overview of the repository.
 2.  **Scaffolding:** Use `/scaffold` to initialize new project components with modern tooling.
 3.  **Iterative Development:** Follow the Discovery -> Plan -> Execute cycle for every feature.
-4.  **Quality Control:** Rely on the `make.py` hook to maintain codebase integrity.
+4.  **Quality Control:** Rely on the `pre-commit` hook to maintain codebase integrity.
 5.  **Releasing:** Use `/release` to automate versioning, changelog updates, and git tagging.
 
 ---