imdone-cli docs

Files and formatting

Understand local issue files, comments, Markdown formatting, and safe editing.

Markdown Formatting Guide

The imdone-cli includes automatic markdown formatting to ensure consistency across your project files. When you run imdone lint or imdone push, the following formatting rules are applied:

Formatting Rules

List Indentation

  • All lists: Uses 4 spaces per indentation level for consistent formatting
  • Ordered lists: Uses 4 spaces per indentation level
  • Unordered lists: Uses 4 spaces per indentation level
  • Mixed lists: All nested lists maintain the 4-space indentation standard
  • Inconsistent indentation will be automatically fixed

Example of proper list formatting:

1. First ordered item
    - First unordered subitem (4 spaces)
        - Nested unordered item (8 spaces)
            - Deeper nested item (12 spaces)
2. Second ordered item
    - Another unordered subitem (4 spaces)

Code Blocks

  • All code blocks must use fenced style with triple backticks (```)
  • Code block indentation is normalized:
    • Fence markers (```) are moved to the left margin
    • Content within code blocks is reduced the same number of spaces as the fence indentation

Emphasis and Strong Styling

  • Emphasis (italics): Use asterisks *like this* instead of underscores
  • Strong (bold): Use double asterisks **like this** instead of underscores

Rules Not Enforced

  • Line length: No maximum line length is enforced
  • Bare URLs: URLs without formatting are allowed
  • Trailing punctuation: Headings can end with punctuation marks

Additional markdownlint Rules

All default markdownlint rules are applied except for the overrides listed above. These include:

  • Consistent heading styles
  • Proper spacing
  • List formatting
  • And many other standard markdown best practices

How Violations Are Fixed

When you run imdone lint or as part of imdone push:

  1. List indentation is automatically fixed
  2. Code block indentation is normalized
  3. markdownlint runs to fix remaining issues
  4. All fixed content is saved back to your files

All fixes are applied automatically so you don’t need to manually correct formatting issues. This ensures that markdown files remain consistently formatted across your project and compatible with Jira integration.

Detailed Documentation

Working with Comments

You can add comments to issues directly from your markdown files. Comments are automatically synchronized when you run imdone push.

How to add a comment:

  1. Open the comments-<ISSUE_KEY>.md file for the issue you want to comment on
    • Jira: comments-SCRUM-31.md
    • GitHub: comments-1.md (issue number)
  2. Add your comment in markdown format between the first line and the first --- separator
  3. Run imdone push to sync the comment to your provider

Example (Jira):

# #TODO Comments: SCRUM-31 Enhance markdown to JIRA conversion

This is my new comment! I can use **bold**, _italic_, and other markdown formatting.

The comment supports multiple lines and will be converted to Jira markup automatically.

---

### Comment 10173 by Jesse Piascik (jpiascik) on 2025-07-22T08:57:41.151-0400

Here's another comment

---

Example (GitHub):

# #TODO Comments: 1 Test issue

This is my new comment! I can use **bold**, _italic_, and other markdown formatting.

GitHub uses markdown natively, so no conversion is needed.

---

### Comment 3832629667 by piascikj (piascikj) on 2026-02-02T02:48:59Z

Here's another comment

---

After running imdone push, your comment will be posted to the issue and the file will be updated to prevent duplicate posting.

Notes:

  • Comments use markdown formatting
  • Jira: Markdown is automatically converted to Jira markup
  • GitHub: Markdown is used natively (no conversion)
  • Only add content between the title line and the first --- separator

Requiring Comments for Tasks

You can enforce that certain tasks must have a comment before they can be pushed to your provider by adding commentRequired:true to the task’s metadata.

Example task with required comment (Jira):

# #TODO Fix critical login bug

This task will require a comment before it can be pushed.

<!--
jira:PROJ-123
commentRequired:true
-->

Example task with required comment (GitHub):

# #TODO Fix critical login bug

This task will require a comment before it can be pushed.

<!--
github:1
commentRequired:true
-->

How it works:

  1. When you run imdone push, the CLI checks if any tasks have commentRequired:true in their metadata
  2. If a required comment is missing, you’ll be prompted to enter one: 
    Comment required for task "Fix critical login bug" (PROJ-123):
  3. The comment is automatically added to the corresponding comments-PROJ-123.md file
  4. The push operation continues normally, syncing both the task and the new comment to Jira

When to use:

  • Critical bugs that need explanation
  • Complex features requiring documentation
  • Tasks that affect multiple team members
  • Any work item that benefits from context or reasoning

Working with Attachments

Imdone CLI automatically synchronizes attachments between your provider (Jira or GitHub) and your local project, making it easy to access files, images, and documents related to your issues without switching to the browser.

Automatic Download During Pull:

When you run imdone pull, all attachments are automatically downloaded to local attachments/ folders within each issue directory:

current-sprint/
├── PROJ-123-Fix_login_bug/        # Jira
│   ├── attachments/
│   │   ├── error-screenshot.png
│   │   ├── debug-log.txt
│   │   └── .metadata.yml
│   ├── comments-PROJ-123.md
│   └── issue-PROJ-123.md
├── 1-Fix_login_bug/               # GitHub
│   ├── attachments/
│   │   ├── plan.md
│   │   └── .metadata.yml
│   ├── comments-1.md
│   └── issue-1.md

What gets downloaded:

  • All attachment types: images, documents, logs, screenshots, etc.
  • Original filenames are preserved
  • File metadata is tracked in .metadata.yml for efficient synchronization
  • Only new or changed attachments are downloaded on subsequent pulls

Attachment Features:

  1. Intelligent Sync: Only downloads attachments that are new or have changed since the last pull
  2. Metadata Tracking: Maintains local metadata to avoid unnecessary re-downloads
  3. Error Handling: Gracefully handles download failures without stopping the pull process
  4. Link Rewriting: Local links ([plan.md](./attachments/plan.md)) are automatically converted to provider URLs on push, and back to local links on pull

Accessing Attachments:

Once downloaded, attachments are available in your local file system:

  • View images directly in your IDE or file explorer
  • Open documents with your preferred applications
  • Reference attachments in issue markdown using relative links — they will be rewritten automatically

Editing Attachments Locally:

You can add, modify, delete, or rename attachments directly in your local file system. When you run imdone push, these changes are automatically synchronized back to your provider:

  1. Add a new attachment: Copy a file into the issue’s attachments/ folder

    • imdone push uploads the file and tracks it in .metadata.yml
    • GitHub: uploaded to the imdone-attachments branch at _imdone-attachments/{issue}/{filename}

  2. Modify an attachment: Edit the file locally (e.g., update a screenshot, revise a document)

    • imdone push uploads the modified file as a new version
    • Jira: old version is preserved (no delete attempt to avoid 403 errors)
    • GitHub: the existing stable branch path is updated using GitHub’s content SHA
    • Safety: if upload fails, the old version is preserved

  3. Delete an attachment: Remove the file from the attachments/ folder

    • Jira: imdone push marks the attachment as deleted with a provider comment and adds it to your local ignored list so it won’t be re-downloaded on pull
    • GitHub: imdone push removes the stable file path from the imdone-attachments branch

  4. Rename an attachment: Rename the file in the attachments/ folder

    • Jira: imdone push uploads the new name, records the rename with a provider comment, and adds the old name to your ignored list
    • GitHub: imdone push writes the new stable branch path and deletes the old branch path

Example Workflows:

# Jira — Add a new attachment
imdone pull
cp ~/Desktop/architecture-diagram.png backlog/current-sprint/PROJ-123/attachments/
imdone push
# ✓ Added: PROJ-123/architecture-diagram.png (256KB)

# GitHub — Add a new attachment
imdone pull
cp ~/Desktop/plan.md backlog/current-sprint/1-Fix_login_bug/attachments/
imdone push
# ✓ Uploaded: 1/plan.md → https://github.com/owner/repo/blob/imdone-attachments/_imdone-attachments/1/plan.md

# Modify an existing attachment (works for Jira and GitHub)
open backlog/current-sprint/1-Fix_login_bug/attachments/plan.md
# (make your edits and save)
imdone push
# ✓ Updated: 1/plan.md

# Delete an attachment
rm backlog/current-sprint/1-Fix_login_bug/attachments/old-notes.md
imdone push
# ✓ Deleted: 1/old-notes.md

# Rename an attachment
mv backlog/current-sprint/1-Fix_login_bug/attachments/draft.md backlog/current-sprint/1-Fix_login_bug/attachments/final.md
imdone push
# ✓ Renamed: 1/draft.md → final.md

Example Directory Structure:

backlog/current-sprint/
├── SCRUM-31-Enhance_markdown_conversion/   # Jira issue
│   ├── attachments/
│   │   ├── my-profile-image.jpeg
│   │   ├── requirements-document.pdf
│   │   └── .metadata.yml
│   ├── comments-SCRUM-31.md
│   └── issue-SCRUM-31.md
├── 42-Add_GitHub_attachments/              # GitHub issue
│   ├── attachments/
│   │   ├── design.png
│   │   └── .metadata.yml
│   ├── comments-42.md
│   └── issue-42.md

Technical Notes:

  • The .metadata.yml file tracks sync status and shouldn’t be manually edited
  • Safety mechanism: New version is uploaded first; old version is only replaced if the upload succeeds
  • GitHub: Attachments are stored on a dedicated imdone-attachments branch under _imdone-attachments/<issue>/...
  • GitHub: Stable branch paths use the local filename; content SHA protects updates from stale writes
  • GitHub: The branch current set determines which attachments pull locally; issue comments are not used as an attachment ledger

Customizing Your JQL Query

You can customize which Jira issues are pulled by modifying the JQL (Jira Query Language) in your project configuration:

Location: .imdone/config.yml

plugins:
  imdone-jira:
    jql: 'project = "YOUR-PROJECT" AND status != Done ORDER BY rank ASC'

Common JQL examples:

# Pull only issues assigned to you
jql: 'project = "PROJ" AND assignee = currentUser() AND status != Done ORDER BY rank ASC'

# Pull issues from specific sprint
jql: 'project = "PROJ" AND sprint in openSprints() ORDER BY rank ASC'

# Pull issues by labels
jql: 'project = "PROJ" AND labels in ("frontend", "backend") ORDER BY rank ASC'

# Pull issues from multiple projects
jql: 'project in ("PROJ1", "PROJ2") AND status != Done ORDER BY rank ASC'

# Pull only high priority issues
jql: 'project = "PROJ" AND priority in ("High", "Highest") ORDER BY rank ASC'

Tips:

  • Use Jira’s Query Builder in the web interface to test your JQL before adding it to config
  • The ORDER BY rank ASC clause ensures issues appear in your backlog priority order
  • After changing JQL, run imdone reset to refresh your local issues with the new query
  • You can use Jira functions like currentUser(), openSprints(), and now()

Temporary JQL Override For Pull

If you only need a broader Jira working set for one pull run, you do not need to edit your saved config.

# Pull a broader set for backlog refinement one time
imdone pull --jql 'project = "PROJ" AND status != Done ORDER BY updated DESC'

# Next plain pull goes back to the saved default query
imdone pull

Use this when you want to do temporary refinement or research against a wider Jira issue set but keep your day-to-day sync scope unchanged. In mixed-provider projects, GitHub still pulls with its configured default query.