multivmlabs
diff --git a/‎.gitignore‎
Lines changed: 5 additions & 0 deletions b/‎.gitignore‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎.npmignore‎
Lines changed: 9 additions & 0 deletions b/‎.npmignore‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎docs/blog/2026-01-15-why-autonomous-coding.md‎
Lines changed: 49 additions & 49 deletions b/‎docs/blog/2026-01-15-why-autonomous-coding.md‎
Lines changed: 49 additions & 49 deletions
diff --git a/‎docs/blog/2026-01-18-connect-your-tools.md‎
Lines changed: 52 additions & 78 deletions b/‎docs/blog/2026-01-18-connect-your-tools.md‎
Lines changed: 52 additions & 78 deletions
@@ -25,3 +25,8 @@ projects/
 
 refs/
 refs/*
+
+# Internal content (social media drafts, marketing plans, articles)
+docs/SEO_MARKETING_PLAN.md
+docs/articles/
+content/
@@ -0,0 +1,9 @@
+# Source maps (not needed for CLI tool consumers)
+dist/**/*.js.map
+dist/**/*.d.ts.map
+
+# Dev/repo files
+docs/
+projects/
+.github/
+*.test.*
@@ -1,84 +1,84 @@
 ---
 slug: why-autonomous-coding
-title: Why Autonomous AI Coding Loops Are the Future
-authors: [ralph]
-tags: [ai, coding, automation, future]
+title: Why autonomous AI coding loops work
+authors: [ruben]
+tags: [ai, coding, automation]
+description: I spent months copy-pasting between ChatGPT and my editor before I realized the loop itself was the problem, not the AI.
+image: /img/blog/ralph-wiggum-technique.png
 ---
 
-# Why Autonomous AI Coding Loops Are the Future
-
-The way we write software is changing. Fast.
+I spent months copy-pasting code between ChatGPT and my editor before I realized I was the bottleneck.
 
 <!-- truncate -->
 
-## The Problem with Traditional AI Coding Assistants
+## The back-and-forth tax
 
-Most AI coding tools today work like this: you ask a question, get an answer, copy-paste, tweak, repeat. It's helpful, but it's still *you* doing the heavy lifting. You're the one:
+You know the drill. Open ChatGPT, describe what you want, get some code back, paste it into your editor, run it, something breaks, copy the error, go back to the chat, paste the error, get a new version, paste that in. I was doing this maybe 15-20 times a day. For months.
 
-- Breaking down the task
-- Managing context
-- Iterating on solutions
-- Running tests
-- Fixing errors
+And every round trip you lose a little bit of context. The model half-forgets what it suggested two messages ago. You lose track of which version you pasted where. Meanwhile you're the one running tests, reading stack traces, deciding what to try next.
 
-What if the AI could do all of that autonomously?
+At some point I realized the AI was doing the easy part -- generating code -- and I was doing everything else. Basically a clipboard manager with opinions.
 
-## Enter Autonomous Coding Loops
+## What if the agent just... kept going?
 
-ralph-starter takes a different approach. Instead of being a passive assistant, it runs **autonomous coding loops**:
+So the idea behind ralph-starter is stupid simple. Instead of you being the middleman, the agent does the whole thing:
 
 ```bash
-ralph-starter run "add user authentication" --loops 5 --test --commit
+ralph-starter run "add user authentication with JWT" --loops 5 --test --commit
 ```
 
-Here's what happens:
+It reads your codebase, writes code, runs your tests. If something fails, it reads the error and fixes it. Then runs tests again. Over and over until things pass or it runs out of loops. You just... go do something else.
 
-1. **Loop 1**: Analyzes the codebase and requirements
-2. **Loop 2**: Implements the core functionality
-3. **Loop 3**: Adds tests and validation
-4. **Loop 4**: Fixes any issues found
-5. **Loop 5**: Polishes and commits
+Here's a real run from last week:
 
-Each loop builds on the previous one. The AI learns from test failures, linter errors, and build issues—then fixes them automatically.
+```
+Loop 1: Read codebase, generated auth middleware and routes
+  → Tests: 3 failed (missing bcrypt import, wrong token expiry, no error handler)
 
-## Why This Matters
+Loop 2: Fixed imports, updated token config, added error handling
+  → Tests: 1 failed (error handler not catching expired tokens)
 
-### 1. Context Persistence
-Traditional chat-based coding loses context. You start fresh each time. Autonomous loops maintain full context across iterations.
+Loop 3: Added expired token case to error handler
+  → Tests: passed
+  → Lint: 2 warnings (unused import, missing return type)
 
-### 2. Validation-Driven Development
-Every change runs through your test suite. Bad code doesn't survive.
+Loop 4: Cleaned up lint issues
+  → Tests: passed, Lint: passed, Build: passed
+  → Committed: feat: add JWT authentication
+```
 
-### 3. Cost Efficiency
-You pay for results, not conversation. A task that might take 20 back-and-forth messages gets done in 3-5 focused loops.
+Four loops, zero copy-pasting, zero babysitting. I reviewed the diff after and it was clean -- I made coffee during loop 2.
 
-## The Specification-First Workflow
+## Why this works better than chatting
 
-The real magic happens when you combine autonomous loops with specs from your existing tools:
+The big difference is context. In a chat, the model kind of forgets what it tried two messages ago. In a loop, the agent sees everything -- its own previous attempts, the full test output, the whole history. It doesn't start over each time.
 
-```bash
-# From a GitHub issue
-ralph-starter run --github "owner/repo#42"
+And errors become free instructions, which is the part that really clicked for me. When `TypeError: Cannot read properties of undefined` shows up in the test output, the agent gets that exact string -- you don't have to describe the problem. It reads the stack trace and acts on it. That is the stuff I was doing manually before, and honestly the agent is better at it than me because it does not skip lines.
 
-# From a Linear ticket
-ralph-starter run --linear "PROJ-123"
+A chat session might take 15-20 messages to land on working code. A loop usually finishes in 3-5 iterations because each one does real work, validates it, and course-corrects. You're paying for results, not conversation.
 
-# From a Notion page
-ralph-starter run --notion "page-id"
-```
+## Where it actually works (and where it doesn't)
 
-Your specs live where your team already works. ralph-starter fetches them and turns them into working code.
+This is not magic though. It works really well when you have:
 
-## What's Next
+- **A clear spec.** "Add password reset flow per the design in issue #42" works great. "Make the auth better" does not.
+- **Tests.** Even crappy ones. Tests give the agent a finish line. Without them it's just vibes.
+- **A linter and type checker.** More automated checks = more signal for the agent to self-correct.
 
-We're just getting started. The future includes:
+The tasks where I've had the best results: implementing a well-scoped feature from a GitHub issue, fixing a bug with a reproducible test case, refactoring code that has good coverage.
 
-- **Multi-agent collaboration**: Specialized agents working together
-- **Learning from feedback**: Improving based on your review comments
-- **CI/CD integration**: Autonomous loops triggered by events
+Where it falls apart: vague requirements with no tests, greenfield projects with no structure yet, anything that needs human judgment about UX. I tried it on a "redesign the dashboard" task once and... yeah. Don't do that.
+
+## It gets even better with real specs
+
+One more thing that made a huge difference. Instead of writing a prompt from scratch, you can point it at an actual GitHub issue:
+
+```bash
+ralph-starter run --from github --project myorg/api --issue 42 --loops 5 --test --commit
+```
 
-The question isn't whether AI will write most code—it's how we'll orchestrate it.
+This fetches the full issue body, comments, linked context -- all of it. The agent gets the same spec your team wrote for a human developer. Except it doesn't skim. It reads the whole thing, every comment, every acceptance criterion. Honestly it's more thorough than I am.
 
 ---
 
-Ready to try autonomous coding? [Get started with ralph-starter](/intro).
+If you want to try it, [the quickstart takes about two minutes](/docs/intro).
@@ -1,120 +1,105 @@
 ---
 slug: connect-your-tools
-title: "Connect Your Tools: From Spec to Code in One Command"
-authors: [ralph]
+title: From spec to code in one command
+authors: [ruben]
 tags: [integrations, github, linear, notion, workflow]
+description: Your specs already live in GitHub, Linear, or Notion. One command pulls them into ralph-starter and starts coding.
+image: /img/blog/connect-your-tools.png
 ---
 
-# Connect Your Tools: From Spec to Code in One Command
-
-Your specifications already exist. They're in GitHub issues, Linear tickets, Notion docs, and markdown files. Why copy-paste them into an AI chat?
+Every feature you build starts with a spec that already exists somewhere. GitHub issue, Linear ticket, Notion doc. It's already written. The annoying part is getting it into your AI tool without losing half of it.
 
 <!-- truncate -->
 
-## The Copy-Paste Problem
-
-Here's a typical workflow with AI coding assistants:
+## The problem I kept running into
 
-1. Open your GitHub issue
-2. Copy the description
-3. Paste into AI chat
-4. Copy linked context
-5. Paste that too
-6. Ask the AI to implement
-7. Copy the code back
-8. Create a branch, commit, push
-9. Update the issue
+I'd open a GitHub issue, read through the description and comments, mentally summarize it, then type a prompt for Claude that captured... maybe 60% of what was actually in the issue. The linked design doc? Forgot to include it. The acceptance criteria someone added in comment #3? Missed that too.
 
-That's a lot of manual work. And context gets lost along the way.
+The spec was right there. I was just a really bad copy-paster. And you know what's dumb? I did this for months before it occurred to me that a script could just fetch the issue directly.
 
-## One Command, Full Context
+## So I made it one command
 
-ralph-starter connects directly to your tools:
+ralph-starter just pulls the spec directly and feeds it to the agent:
 
 ```bash
-# Fetch from GitHub and implement
-ralph-starter run --github "myorg/myrepo#123" --commit --pr
+ralph-starter run --from github --project myorg/api --issue 42 --loops 5 --test --commit
+```
 
-# Fetch from Linear
-ralph-starter run --linear "PROJ-456" --commit
+What happens here: it authenticates with GitHub using your existing `gh` CLI session, grabs issue #42 -- body, all comments, labels, linked references, everything -- and hands it all to the coding agent. Then the agent implements the feature, runs your tests after each loop, and commits when everything passes.
 
-# Fetch from Notion
-ralph-starter run --notion "abc123" --commit
-```
+No tab-switching, no summarizing, no "let me paste the relevant parts." The agent gets the raw spec, the whole thing.
 
-Everything flows automatically:
-- **Spec** → fetched from your tool
-- **Context** → linked files, comments, attachments
-- **Implementation** → autonomous coding loops
-- **Validation** → tests, lint, build
-- **Delivery** → commit, push, PR
+## GitHub issues and PRs
 
-## Supported Integrations
+This is the one I use the most, by far. Just point it at an issue:
 
-### GitHub Issues & PRs
+```bash
+ralph-starter run --from github --project owner/repo --issue 123
+```
+
+It pulls the title, body, comments, file references. If the issue links to other issues, those come along too. Basically the agent sees everything your team wrote -- which is usually way more context than what I'd remember to paste.
+
+PRs work the same way, which is great for when you get review feedback and don't want to fix 12 nits by hand:
 
 ```bash
-ralph-starter run --github "owner/repo#123"
+ralph-starter run --from github --project owner/repo --issue 456 --loops 3 --test
 ```
 
-Fetches:
-- Issue/PR title and body
-- Comments and discussion
-- Linked files and references
-- Labels and metadata
+## Linear tickets
 
-### Linear Tickets
+If your team uses Linear, same deal:
 
 ```bash
-ralph-starter run --linear "PROJ-123"
+ralph-starter run --from linear --project PROJ --issue PROJ-123 --commit
 ```
 
-Fetches:
-- Ticket title and description
-- Sub-issues and parent context
-- Attachments and links
-- Priority and status
+Grabs the ticket description, sub-issues, attachments, priority. One thing I've noticed: Linear tickets tend to be really well-structured compared to GitHub issues, so the agent gets cleaner input and the results are usually better on the first try. Not always, but noticeably.
+
+## Notion pages
 
-### Notion Pages
+For teams that write everything in Notion (I've been there):
 
 ```bash
-ralph-starter run --notion "page-id"
+ralph-starter run --from notion --project "page-id" --loops 5 --test
 ```
 
-Fetches:
-- Page content (markdown converted)
-- Linked databases
-- Child pages
-- Embedded files
+The page content gets converted to markdown, and child pages and linked databases come along for the ride. This is especially nice for those longer specs -- you know, the ones with 3 sections and a table and a "Notes from the last meeting" block. Try pasting all of that into a chat window. Actually, don't.
 
-### Local Files & URLs
+## Local files and URLs
+
+Sometimes the spec is just a markdown file in your repo:
 
 ```bash
-# Local spec file
-ralph-starter run --from ./specs/auth-feature.md
+ralph-starter run --from ./specs/auth-feature.md --test --commit
+```
 
-# Remote URL
+Or a URL:
+
+```bash
 ralph-starter run --from "https://example.com/spec.md"
 ```
 
-## Combining Sources
+## Combining sources (this is the good part)
 
-Need context from multiple places? Combine them:
+OK so the thing I actually use the most in practice is combining a GitHub issue with extra local context:
 
 ```bash
 ralph-starter run \
-  --github "owner/repo#123" \
-  --from ./additional-context.md \
+  --from github --project owner/repo --issue 123 \
+  --context ./docs/api-conventions.md \
   --loops 5 \
+  --test \
   --commit
 ```
 
-## Authentication
+The agent gets the issue spec plus your project conventions in one shot. This is where the quality jumps noticeably. Before I started doing this, the agent would generate code that worked but didn't follow our patterns -- wrong naming conventions, different error handling style, that kind of thing. Now it matches the rest of the codebase on the first try most of the time.
 
-Set up once, use everywhere:
+## Setting up auth
+
+One-time setup, takes like 30 seconds:
 
 ```bash
-# GitHub (uses gh CLI)
+# GitHub (uses your existing gh CLI login)
 gh auth login
 
 # Linear
@@ -124,17 +109,6 @@ ralph-starter config set linear.apiKey lin_api_xxx
 ralph-starter config set notion.token secret_xxx
 ```
 
-## What's Next
-
-We're adding more integrations:
-- Jira
-- Asana
-- Trello
-- Slack threads
-- Discord messages
-
-Your workflow, your tools, your way.
-
 ---
 
-Ready to connect? Check out the [integrations guide](/sources/overview).
+The full list of supported sources is in the [integrations guide](/docs/sources/overview).