syabro/linear-code.md

Created July 18, 2025 13:18

Star (0) You must be signed in to star a gist
Fork (0) You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/syabro/60059b6f09abbc45fb4034203dc276f0.js"></script>
Save syabro/60059b6f09abbc45fb4034203dc276f0 to your computer and use it in GitHub Desktop.

Download ZIP

Raw

linear-code.md

read @CLAUDE.md

Execute a single task from the to-do list for a Linear issue.

$ARGUMENTS (Linear issue ID: PRE-XXX)

IF NO ARGUMENTS PROVIDED EXTRACT ID from current branch name

IMPORTANT:

MUST operate on the current git branch.
MUST follow the implementation details of the specified task.
MUST run tests and commit only after they pass.

Read task description and in comments using bash

lr issue $ARGUMENTS -d; lr issue $ARGUMENTS -c`

Step 1: Identify and Confirm Next Task

CC ACTION:

Read the file .local/plan-$ARGUMENTS-todo.md.
Find the first line that starts with - [ ]. This is the next task.
If no incomplete tasks are found, report "All tasks are complete." and stop.
Display the task details (title, description, completion criteria) to the user.

Step 2: Implement the Task

CC ACTION:

Carefully read the task description and its completion criteria.
Think what you need and ask gemini to provide you existing stuff
Implement the required code changes. Use file reading and editing tools as needed.
Adhere to the "Development Philosophy" from the planning phase (simple, minimal code).

Step 3: Test Implementation

CC ACTION:

Run the tests specified in the task's completion criteria (e.g., cd $ROOT/backend && uv run manage.py test).
If tests fail: a. Analyze the errors. b. Attempt to fix the code. c. Re-run the tests. d. If tests still fail after 2 attempts, stop and report the failure and the error logs to the user.
Ask gemini to test changes using /check-changes-gemini command

Step 4: Commit Changes

CC ACTION:

Once all tests pass, generate a commit message based on the task title. The message must follow the rules in AGENTS-TEXT.md.
Show the generated commit message to the user and ask for approval.
If approved, run git commit.

Step 5: Mark Task as Complete

CC ACTION:

Edit the .local/plan-$ARGUMENTS-todo.md file.
Change the - [ ] to - [x] for the task that was just completed.
Report that the task is done and the to-do list has been updated.

Repeat from step 1

Raw

linear-create.md

read @CLAUDE.md

You are an assistant that helps create well-defined Linear issues from unstructured thoughts.

Linear Issue Creation Workflow

Gather Thoughts:
- Ask me to provide a "brain dump" of all my thoughts, notes, and context for the new issue in a single block of text.
Structure with AI:
- Once I provide the text, use the following prompt to structure it with an AI model.
- AI Structuring Prompt: "read @AGENTS-TEXT.md
  
  You are an expert product manager. Your task is to analyze the following unstructured text and transform it into a complete, well-structured Linear issue.
  
  --- USER'S THOUGHTS --- <USER_PROVIDED_TEXT>
  
  --- YOUR TASK --- Analyze the text and extract or generate the following:
  1. Title: Create a concise and descriptive title for the issue.
  2. Type: Determine if this is a Bug, Feature, or Chore.
  3. Description:
    - Write a clear, structured description following the guidelines in @AGENTS-TEXT.md.
    - Focus on the business purpose (the 'what' and 'why').
    - For Bugs, use ## Steps to Reproduce and ## Expected Behavior.
    - For Features, use ## Problem and ## Proposed Solution.
    - For Chores, summarize the task to be done.
  4. Priority: Suggest a priority (Urgent, High, Medium, Low) based on the tone and content. If not clear, default to Medium.
  --- FORMATTING --- Present the output as a clean, ready-to-use block for Linear, clearly separating the title, description, and other fields. "
Enrich with Code Context:
- Take the draft issue from the previous step.
- Use the following prompt with gemini -p to analyze the codebase and enhance the issue.
- AI Code Analysis Prompt: "read @AGENTS-TEXT.md
  
  You are an expert senior software engineer. Your task is to analyze the current codebase to enrich a draft Linear issue with technical context.
  
  --- DRAFT LINEAR ISSUE ---
  - Title: <DRAFT_TITLE>
  - Description: <DRAFT_DESCRIPTION>
  --- YOUR TASK ---
  1. Analyze Codebase: Based on the draft issue, perform a semantic search of the workspace to find relevant files, components, functions, or APIs.
  2. Generate Implementation Notes:
    - Create a collapsible section for implementation notes (+++ Implementation Notes).
    - The notes must follow the guidelines in @AGENTS-TEXT.md for technical notes (high-level pointers, not a spec).
  3. Format Output: Provide the collapsible Implementation Notes block. If no relevant context is found, state that. "
Verify with AI:
- Take the enriched issue details and the original user text.
- Use the following prompt with gemini -p to double-check the result.
- AI Verification Prompt: "read @AGENTS-TEXT.md
  
  You are a quality assurance specialist. Your task is to verify if the structured Linear issue accurately and completely represents the user's original, unstructured thoughts.
  
  --- USER'S ORIGINAL THOUGHTS --- <USER_PROVIDED_TEXT>
  
  --- STRUCTURED LINEAR ISSUE ---
  - Title: <GENERATED_TITLE>
  - Type: <GENERATED_TYPE>
  - Description: <GENERATED_DESCRIPTION>
  - Priority: <GENERATED_PRIORITY>
  --- YOUR TASK ---
  1. Compare: Does the structured issue capture all the key points from the original text?
  2. Identify Gaps: Are there any missing details, requirements, or context?
  3. Check for Inaccuracies: Does the structured issue contain any information not present in or misinterpreted from the original text?
  4. Provide Feedback: If there are discrepancies, provide specific suggestions for improvement. If it is accurate, confirm that it looks good. "
Review and Refine:
- Show me the AI-generated (enriched and verified) title, type, description, priority, and implementation notes for my approval.
- If gemini -p suggested improvements, show them to me as well.
- If I don't approve, ask for my feedback and corrections. Then, incorporate my feedback and repeat the structuring (Step 2), enrichment (Step 3), and verification (Step 4) steps until I am satisfied.
Create Issue:
- Once I approve the final version, create the issue in Linear by calling the MCP server's createLinearIssue method. The final description sent to Linear should be a combination of the main description and the implementation notes.
Confirmation:
- Show me the URL of the newly created Linear issue.

Output Structure

**Title:** <GENERATED_TITLE>

**Type:** <GENERATED_TYPE>

**Priority:** <GENERATED_PRIORITY>

**Description:**
<GENERATED_DESCRIPTION>

---

+++ **Implementation Notes**

<GENERATED_IMPLEMENTATION_NOTES>
+++

Example Output

**Title:** Make plugin update-checking faster and more reliable

**Type:** Feature

**Priority:** High

**Description:**
### Problem

Our plugin database has old versions. We have a script that checks for updates, but it has two problems:

1.  It searches everywhere for new versions instead of using the official plugin website URLs we already have.
2.  When it finds a new version, we don't know what to do next.

### Proposed Solution

Fix the update script to work better:

1.  Use the official plugin website URLs we have stored to find new versions.
2.  Use the Perplexity.ai API to check for updates.
3.  When a new version is found, show the plugin name, current version, new version, and source URL.
4.  Create clear steps for what to do after finding updates.

---

+++ **Implementation Notes**

- **Script:** `backend/software/management/commands/check_updates.py`
- **Key Function:** `check_latest_version`
- **Data Source:** Use the `url` field from the `Software` model.
- **Goal:** The script should find the new version and the source URL.

+++

Raw

linear-finish.md

read @CLAUDE.md

You are an assistant that summarizes completed work and marks Linear issues as done.

Linear Finish Workflow

Gather Context:
- To understand the work that was done, perform the following:
  - Fetch the original issue description from Linear.
  - Get all git commit messages that contain the Linear issue ID (e.g., PRE-XXX).
  - If no commits found: Stop and report "No commits found for this issue. Cannot generate summary."
Generate Work Summary:
- Use the gathered context to generate a summary with the following prompt:
- AI Summary Generation Prompt: "read @AGENTS-TEXT.md
  
  You are a product manager summarizing completed work for a team update. Your summary must be clear, concise, and focused on the value delivered.
  
  --- CONTEXT ---
  - Original Task: <LINEAR_ISSUE_DESCRIPTION>
  - Commits: <GIT_COMMIT_MESSAGES>
  --- YOUR TASK --- Generate a work summary with the following format:
  
  ✅ COMPLETED
  
  [One bold, outcome-focused header line summarizing what was achieved]
  - [Bullet point describing the first key result or change from a user/business perspective]
  - [Bullet point for the second key result]
  - [Bullet point for the third key result]
  --- GUIDELINES ---
  - The summary must follow the guidelines in @AGENTS-TEXT.md.
  - Focus on the outcome and value delivered.
  - Keep each bullet point to a single line.
  - Do not mention tests unless testing was the only goal of the task. "
Review and Refine:
- Show me the generated summary for approval.
- Ask: "❓ Does this summary look good? Should I post it and mark the issue as done?"
- If I don't approve, ask for my feedback and corrections, then repeat Step 2.
Finalize Issue:
- Once I approve, create a comment in Linear with the final summary.
- Update the issue status to "Done" (ID: 199e0ead-104a-495e-af38-a6898f1c9b81).
- Confirm with: "✅ Issue marked as done."

Raw

linear-plan.md

read @CLAUDE.md

Create HIGH-LEVEL plan for Linear issue.

$ARGUMENTS (Linear issue ID: XXX or PRE-XXX)

IMPORTANT:

MUST FOLLOW PLAN STRICTLY. MUST NOT RUN ANY COMMANDS OR SCRIPTS NOT SPECIFIED IN THE PLAN MUST NOT RUN COMMANDS INSIDE BASH SUBSTITUTIONS MANUALLY OR DO SOMETHING TO EMUALTE THEM. EG

$(cat ...)
$(lr) .local folder exists! Don't check for it!

Step 1: Generate Plan with Questions

First check existing plans:

# Check for existing plans
if [ -f ".local/plan-$ARGUMENTS-final.md" ]; then
    echo "✅ Final plan already posted to Linear"
    cat ".local/plan-$ARGUMENTS-final.md"
    echo "\nCreate new plan anyway? (y/n)"
    # If no: stop
elif [ -f ".local/plan-$ARGUMENTS-draft.md" ]; then
    echo "📝 Draft plan exists (not posted)"
    echo "Options: Show / Regenerate / Edit"
    # Show: skip to Step 2
    # Regenerate: continue below
    # Edit: $EDITOR .local/plan-$ARGUMENTS-draft.md then Step 2
fi

Run this single gemini command (the $(...) are bash substitutions within the prompt):

CC ACTION: First ensure directory exists, then execute the gemini command:

gemini -p "
read @AGENTS-TEXT.md

Create a high-level plan for this Linear issue:

$(lr issue $ARGUMENTS -d)

Comments:
$(lr issue $ARGUMENTS -c)

Provide a strategic plan with:

REQUIREMENTS: [one line summary]

UNCERTAINTY LEVEL: [Low/Medium/High - explain why]

QUESTIONS:
- [Any clarifications needed before implementation]
- [Or write 'None' if everything is clear]
[IMPORTANT: Format as numbered list when displaying to user]

APPROACH:
- Backend: [strategic changes and why]
- Frontend: [strategic changes and why]
- App: [strategic changes and why]

USER JOURNEY:
1. [What user wants to do]
2. [How they do it]
3. [What they see/experience]

SCOPE:
- Included: [what's in this task]
- NOT included: [what's out of scope]

Focus on WHAT needs to be done and WHY, not implementation details.
" --all_files > .local/plan-$ARGUMENTS-draft.md

Step 2: Review & Iterate

IMPORTANT: Do NOT edit the draft file directly. Show the complete plan first, then follow user's choice.

Show COMPLETE plan from .local/plan-$ARGUMENTS-draft.md including:
- ALL questions exactly as written (do not summarize)
- Full uncertainty level explanation
- Complete approach and scope

If uncertainty is High or questions exist:

Convert Gemini's bullet points to numbered list

Show each question as a numbered list:

Questions from Gemini:
1. Should the installation panel be a new, dedicated page (e.g., `/downloads`) or a persistent UI element?
2. Should the panel show a history of all past installations, or only those from the current session?
3. [Any other questions exactly as written]

Please provide answers numbered 1, 2, 3...

Regenerate with ONE command:

gemini -p "read @AGENTS-TEXT.md

Update plan based on:
[paste your numbered answers]

Previous plan:
$(cat .local/plan-$ARGUMENTS-draft.md)" --all_files > .local/plan-$ARGUMENTS-draft.md

Ask: "✅ Approve / 📝 Edit / 🔄 Rethink?"

What these mean:
- ✅ Approve = Plan looks good, ready to post to Linear
- 📝 Edit = You'll manually edit the file in your text editor
- 🔄 Rethink = Gemini will regenerate based on your feedback
Actions:
- Approve → Plan is good, skip to Step 3 to post to Linear
- Edit → You want to manually edit the file:
```
$EDITOR .local/plan-$ARGUMENTS-draft.md
```
  After you save and exit the editor, show the updated plan and ask again
- Rethink → You want gemini to regenerate. Ask "What needs to change?" then:
```
gemini -p "read @AGENTS-TEXT.md

Update plan based on feedback: 
[user feedback]

Previous plan:
$(cat .local/plan-$ARGUMENTS-draft.md)" --all_files > .local/plan-$ARGUMENTS-draft.md
```
  Go back to start of Step 2

Step 3: Post to Linear

Format and post:

### Implementation Plan

[Content from approved draft]

---
_High-level strategic plan_

Save final: mv .local/plan-$ARGUMENTS-draft.md .local/plan-$ARGUMENTS-final.md

Rules:

ALWAYS start gemini prompts with read @AGENTS-TEXT.md
Plan includes questions & uncertainty
Strategic focus (what/why not how)
Iterate until uncertainty is addressed
All plans saved for reference
NEVER summarize questions - show ALL questions exactly as Gemini wrote them
ALWAYS format questions as numbered list for easy reference (1, 2, 3...)
NEVER edit draft files directly - use $EDITOR or regenerate with gemini

Raw

linear-todo.md

read @CLAUDE.md

Start implementing a Linear issue based on a plan.

$ARGUMENTS (Linear issue ID: PRE-XXX)

IMPORTANT:

MUST FOLLOW PLAN STRICTLY.
MUST NOT RUN ANY COMMANDS/SCRIPTS/TOOLS NOT SPECIFIED IN THE PLAN
MUST NOT RUN COMMANDS INSIDE BASH SUBSTITUTIONS MANUALLY OR DO SOMETHING TO EMUALTE THEM. EG
- $(cat ...)
- $(lr)
MUST NOT CREATE .local - it exists!

Step 1: Generate To-Do List

CC ACTION:

Check if .local/plan-$ARGUMENTS-todo.md exists. If so, show it and ask to proceed to step 2. Stop if user says no.
If it does not exist, generate it with the following command:

gemini -p "
read @AGENTS-TEXT.md

Analyze the following Linear issue and user comments to generate a step-by-step checklist of development tasks for an AI assistant. The implementation plan is in the issue description.

**Issue Details:**
$(lr issue $ARGUMENTS -d)
**Issue Comments (must include plan):**
$(lr issue $ARGUMENTS -c)


**User Comments:**
$ADDITIONAL_ARGUMENTS

**Instructions:**
1.  **Analyze Existing Code:** Before generating tasks, thoroughly analyze the existing codebase to understand the current implementation and context.
2.  **Deconstruct the Plan:** Break down the high-level plan into a sequence of small, concrete, and **atomic** coding tasks. Each task must represent a single, logical change that can be tested and committed independently.
3.  **Development Philosophy:** Adhere to a startup mindset. This means:
    - Prioritize simple, minimal, and compact code.
    - Avoid enterprise patterns and over-engineering.
    - Focus on the core user path, not every possible edge case. "Less is more."
4.  **Detailed Tasks:** For **each task**, provide the following:
    - A clear, action-oriented title (e.g., "CREATE API endpoint for downloads").
    - A one-sentence, user-focused summary of what the task achieves, placed directly under the title.
    - A bulleted list of definition of done. What must be presented. MUST BE SHORT AND LACONIC.
5.  **Testing:** All non-UI code (e.g., backend logic) must be covered by tests that do not use mocks.
6.  **Final Review:** Before finishing, double-check the generated to-do list against all instructions to ensure every requirement has been met.
7.  **Output Format:** The output must be a markdown checklist.

**Example Output:**
\`\`\`markdown
### To-Do List
- [ ] **Task 1: Add `last_downloaded_at` to Software model**
      Track when software is downloaded to provide users with recent activity information.
      - The `Software` model in `software/models.py` has a new `last_downloaded_at` field.
      - A database migration has been created.

- [ ] **Task 2: Create API endpoint for downloads**
      Provide a secure way for the frontend to request a software download link.
      - A new endpoint exists at `/api/software/{id}/download/`.
      - The endpoint is tested (without mocks) and returns a valid download URL.
      - All backend tests pass (`cd backend && uv run manage.py test`).
\`\`\`
" --all_files > .local/plan-$ARGUMENTS-todo.md

Step 2: User Approval

CC ACTION:

Show the EXACT GENERATED to-do list from .local/plan-$ARGUMENTS-todo.md to the user.
Ask for approval: "Do you approve this plan? (y/n/comment)".

If the user provides comments, regenerate the plan with the following command and repeat this step:

gemini -p "
read @AGENTS-TEXT.md

The user has provided feedback on the to-do list. Please regenerate it based on their comments.

**Previous To-Do List:**
$(cat .local/plan-$ARGUMENTS-todo.md)

**User Feedback:**
$USER_COMMENTS

Follow all original instructions, including format and development philosophy.
" --all_files > .local/plan-$ARGUMENTS-todo.md

If the user approves ("y"), continue to the next step.
If the user rejects ("n"), stop.

Step 3: Create and Checkout Branch

CC ACTION:

Get a short, descriptive slug for the branch name from the issue title.
Create and checkout a new branch: git checkout -b pre-$ARGUMENTS-<slug>

Step 4: Implement To-Do List

CC ACTION:

Read the to-do list from .local/plan-$ARGUMENTS-todo.md.
For each item in the list, perform the following: a. Implement the task. b. Run the appropriate tests (make supercheck or specific tests for backend/frontend/app). c. If tests pass, commit the changes with a descriptive message. d. If tests fail, fix the errors and repeat the process.
Mark the task as complete and move to the next one.

Step 5: Report Progress

CC ACTION: Once all tasks are completed, provide a summary report of the work done.