From 031ca831bf725c4b4ca4cf673f55f9e143cd3b2e Mon Sep 17 00:00:00 2001
From: Warren Lee <5959690+wrn14897@users.noreply.github.com>
Date: Tue, 17 Mar 2026 16:02:54 -0700
Subject: [PATCH] docs: add OC commands (#1933)

Add two new OpenCode command specifications for Linear ticket workflows:
- `do-linear.md`: Full workflow for fetching, implementing, testing, and opening a PR for a Linear ticket
- `plan-linear.md`: Research and planning workflow for creating implementation plans from Linear tickets

Ported from EE
---
 .opencode/commands/do-linear.md   | 54 +++++++++++++++++++++++++++++++
 .opencode/commands/plan-linear.md | 22 +++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 .opencode/commands/do-linear.md
 create mode 100644 .opencode/commands/plan-linear.md

diff --git a/.opencode/commands/do-linear.md b/.opencode/commands/do-linear.md
new file mode 100644
index 00000000..57aadea6
--- /dev/null
+++ b/.opencode/commands/do-linear.md
@@ -0,0 +1,54 @@
+---
+description:
+  Fetch a Linear ticket, implement the fix/feature, test, commit, push, and
+  raise a PR
+---
+
+Look up the Linear ticket $ARGUMENTS. Read the ticket description, comments, and
+any linked resources thoroughly.
+
+## Phase 1: Understand the Ticket
+
+- Summarize the ticket — what is being asked for (bug fix, feature, refactor,
+  etc.)
+- Identify acceptance criteria or expected behavior from the description
+- Note any linked issues, related tickets, or dependencies
+
+If the ticket description is too vague or lacks enough information to proceed
+confidently, **stop and ask me for clarification** before writing any code.
+Explain exactly what information is missing and what assumptions you would need
+to make.
+
+## Phase 2: Plan and Implement
+
+Before writing code, read the relevant documentation from the `agent_docs/`
+directory to understand architecture and code patterns.
+
+1. Explore the codebase to understand the relevant code paths and existing
+   patterns
+2. Create an implementation plan — which files to change, what approach to take
+3. Implement the fix or feature following existing codebase patterns
+4. Keep changes minimal and focused on the ticket scope
+
+## Phase 3: Verify
+
+Run lint and type checks, then run the appropriate tests based on which packages
+were modified:
+
+1. Run `make ci-lint` to verify lint and TypeScript types pass
+2. Run `make ci-unit` to verify unit tests pass across all packages
+3. If any checks fail, fix the issues and re-run until everything passes
+
+## Phase 4: Commit, Push, and Open PR
+
+1. Create a new branch named `<current-user>/$ARGUMENTS-<short-description>`.
+   Use the current git/OS username when available, and use `whoami` as a
+   fallback to determine the prefix (e.g. `warren/HDX-1234-fix-search-filter`)
+2. Commit the changes using conventional commit format (e.g. `feat:`, `fix:`,
+   `chore:`) and reference the ticket ID
+3. Push the branch to the remote
+4. Open a pull request with:
+   - Title: `[$ARGUMENTS] <description>`
+   - Body: Use `.github/pull_request_template.md` as the template and fill it in
+     with the relevant summary, testing notes, and Linear ticket link
+   - Label: Attach the `ai-generated` label
diff --git a/.opencode/commands/plan-linear.md b/.opencode/commands/plan-linear.md
new file mode 100644
index 00000000..970e8554
--- /dev/null
+++ b/.opencode/commands/plan-linear.md
@@ -0,0 +1,22 @@
+---
+description: Research a Linear ticket and create an implementation plan
+agent: plan
+---
+
+Look up the Linear ticket $ARGUMENTS. Read the ticket description and all
+comments on the ticket thoroughly.
+
+Based on your research of the ticket, come up with a detailed implementation
+plan. The plan should include:
+
+1. **Summary** — A concise summary of what the ticket is asking for
+2. **Context** — Relevant information gathered from the ticket description and
+   comments
+3. **Approach** — Step-by-step implementation plan with specific files and
+   components to modify
+4. **Testing** — How the changes should be tested
+5. **Open Questions** — Any ambiguities or decisions that need clarification
+
+Before writing the plan, explore the codebase to understand the relevant code
+paths and existing patterns. Reference specific files and line numbers where
+changes will be needed.