feat: add Twitter thread for mdflow getting started guide

[johnlindquist]

Created a 5-tweet thread that shows step-by-step progression:

• Tweet 1: Hook about building AI agents quickly
• Tweet 2: Simplest example (basic .claude.md file)
• Tweet 3: Template variables for reusability
• Tweet 4: Power features (imports, globs, commands)
• Tweet 5: Call to action with all features

Includes working example files that can be demonstrated.

Summary by CodeRabbit

• New Features

  • Added example debugging templates demonstrating code analysis workflows with Claude.
  • Added PR review template for analyzing changes and identifying issues.

• Documentation

  • Added comprehensive Twitter thread guide explaining mdflow capabilities, including markdown frontmatter configuration, template variables, code imports via glob patterns, and CLI integration for AI-powered workflows.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Five new files were added to demonstrate mdflow functionality: three Claude-style debugging and PR review prompt templates, one intentionally buggy TypeScript example, and a comprehensive Twitter thread guide explaining mdflow usage patterns including debugging, templating, code imports, and CLI integration.

Changes

Cohort / File(s)	Summary
Claude example templates examples/twitter-thread/1-simple-debug.claude.md, examples/twitter-thread/2-template-debug.claude.md, examples/twitter-thread/3-pr-review.claude.md	Three new prompt files for Claude workflows: a simple debug prompt, a reusable TypeScript debug template with variable substitution, and a PR review directive with git diff analysis and TypeScript targeting.
Example code examples/twitter-thread/buggy.ts	TypeScript function demonstrating an off-by-one loop error (condition uses <= instead of <) that can access out-of-bounds array indices. Intended as sample code for debugging exercises.
Documentation twitter-thread.md	Comprehensive guide as a five-tweet thread explaining mdflow concepts: converting markdown with frontmatter to AI agents, template variables, language overrides, code context imports via globs, diffs, and CLI usage patterns.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• examples/twitter-thread/buggy.ts: Verify the intentional bug (off-by-one error) is accurately documented and appropriate for demonstration purposes
• twitter-thread.md: Confirm example snippets and commands are accurate and representative of mdflow capabilities

Poem

🐰 A thread of examples, both clever and clear,
With templates and debug files without fear,
One buggy old function to test and debug,
And docs that explain every mdflow hug! 🧵✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a Twitter thread file that serves as a getting started guide for mdflow.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/mdflow-twitter-thread-01Jyv9gxJn7uUiDFgDo8cGak

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 15c38dc and 5e3219d.

📒 Files selected for processing (5)

• examples/twitter-thread/1-simple-debug.claude.md (1 hunks)
• examples/twitter-thread/2-template-debug.claude.md (1 hunks)
• examples/twitter-thread/3-pr-review.claude.md (1 hunks)
• examples/twitter-thread/buggy.ts (1 hunks)
• twitter-thread.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.md: Parse YAML frontmatter in markdown files for agent configuration
Use _ prefix for template variables (e.g., _varname) in frontmatter and body templates
System keys in agent frontmatter (_varname, _stdin, env, $1, $2, etc.) are consumed by md and not passed to the command
All non-system frontmatter keys are passed directly as CLI flags to the specified command
Use LiquidJS template syntax for variable substitution in markdown bodies (variables, conditionals, filters)
Use positional mapping ($1, $2) in frontmatter to map body or positional args to specific CLI flags
Implement imports in markdown files using syntax: basic (@./path.md), globs (@./src/**/*.ts), line ranges (@./file.ts:10-50), symbols (@./file.ts#InterfaceName), commands (!`cmd`), and URLs (@https://example.com/file.md)

Files:

• examples/twitter-thread/2-template-debug.claude.md
• twitter-thread.md
• examples/twitter-thread/3-pr-review.claude.md
• examples/twitter-thread/1-simple-debug.claude.md

🪛 LanguageTool

examples/twitter-thread/2-template-debug.claude.md

[style] ~5-~5: Consider using a different verb for a more formal wording.
Context: ...--- Debug this {{ _language }} code and fix any issues: {{ _stdin }}

(FIX_RESOLVE)

twitter-thread.md

[uncategorized] ~66-~66: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...utput, even specific functions - all in markdown. ## Tweet 5/5 - Call to Action mdflow ...

(MARKDOWN_NNP)

examples/twitter-thread/1-simple-debug.claude.md

[style] ~4-~4: Consider using a different verb for a more formal wording.
Context: ...--- model: opus --- Debug this code and fix any issues

(FIX_RESOLVE)

🪛 markdownlint-cli2 (0.18.1)

twitter-thread.md

76-76: Bare URL used

(MD034, no-bare-urls)

🔇 Additional comments (8)

examples/twitter-thread/1-simple-debug.claude.md (1)

1-4: LGTM! Clean and effective template.

The YAML frontmatter and instruction are correctly structured according to mdflow conventions. The model key will be passed as a CLI flag as expected.

examples/twitter-thread/3-pr-review.claude.md (1)

1-11: Excellent demonstration of mdflow's import capabilities!

The template correctly uses glob imports (@./src/**/*.ts) and command output (!`git diff main`) according to the coding guidelines. This provides a practical example of combining code context with dynamic git changes for PR review.

examples/twitter-thread/2-template-debug.claude.md (1)

1-7: Perfect example of mdflow template variables!

The template correctly follows coding guidelines:

• _language uses the required _ prefix for template variables
• {{ _stdin }} properly references the system key for input
• LiquidJS syntax is accurate for variable substitution

This demonstrates template reusability effectively.

Based on coding guidelines, template variables and system keys are correctly implemented.

examples/twitter-thread/buggy.ts (1)

1-15: Intentional bug correctly demonstrates debugging use case.

The off-by-one error in the loop condition (i <= items.length instead of i < items.length) is intentional and serves as a perfect example for the debugging templates in this PR. This will cause items[i] to access undefined on the final iteration, which is exactly the kind of bug the mdflow debugging workflow is designed to catch.

twitter-thread.md (4)

12-27: Clear introduction to mdflow basics.

The simple example effectively demonstrates the core concept: YAML frontmatter becomes CLI flags, and the extension determines the AI provider. This matches the actual 1-simple-debug.claude.md file and provides a gentle entry point.

---

29-47: Excellent demonstration of template variables.

The template example correctly shows:

• _language with required _ prefix for template variables
• {{ _stdin }} for input consumption
• Both piping and CLI override patterns

This matches the coding guidelines and demonstrates mdflow's templating power effectively.

Based on coding guidelines, template variable syntax is correctly documented.

---

49-66: Import syntax perfectly demonstrates mdflow's power.

The PR review example correctly showcases:

• Glob imports: @./src/**/*.ts ✓
• Command output: !`git diff main` ✓

Both patterns match the coding guidelines and demonstrate how mdflow can inject rich context into AI prompts. This is a compelling use case that ties together the previous examples.

---

68-82: Strong call-to-action with comprehensive feature list.

The CTA effectively summarizes mdflow's capabilities and provides immediate next steps. The bare URL at line 76 is perfectly appropriate for a Twitter thread document where users expect clickable links.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}