The non-engineer's development guardrails — by Dojo Coding Labs
Juan is Head of Product & Growth at Dojo Coding Labs. He's not an engineer. He's a product guy who lives in Linear, thinks in user stories, and has strong opinions about button colors.
One day Juan decided he was tired of writing PRDs and waiting. He wanted to contribute to the codebase. The engineers were... concerned.
"What if he pushes to main?" "What if he duplicates work someone's already doing?" "What if he skips the spike and just starts coding?" "What if Greptile roasts him and he doesn't fix it?"
So Juan did what any self-respecting Head of Product would do: he built guardrails for himself.
The result is juan-workflow — a Claude Code plugin that enforces the full development lifecycle every single time Juan sits down to code. Spike first. Check for duplicates. Get Greptile approval. Assign a human reviewer. No shortcuts.
The engineers love it. Juan ships code now. Nothing breaks. And the workflow is so good the whole team uses it.
Open-sourced because if Juan can do it, anyone can. 🤷
One command — /juan-workflow:juan-is-working — orchestrates your entire dev session:
Phase 0 🔍 Setup Learn your team's patterns (first run only)
Phase 1 🎯 Discovery What are we building? Assess scope.
Phase 2 🔎 Duplicates Check Linear + GitHub for existing work
Phase 3 📌 Spike Create spike in Linear, brainstorm, document
Phase 4 🏗️ Build Create task, branch, implement, lint, test
Phase 5 🚀 PR + Review Push PR, wait for Greptile, address feedback
Phase 6 👋 Handoff Assign reviewer (round-robin), update Linear
Every phase confirms before advancing. Everything is cross-linked (Linear ↔ GitHub). Nothing falls through the cracks.
# In Claude Code:
/plugin marketplace add DojoCodingLabs/juan-workflow
/plugin install juan-workflow@juan-workflowThat's it. Type /juan-workflow:juan-is-working and you're off.
# Update the marketplace catalog first:
/plugin marketplace update DojoCodingLabs/juan-workflow
# Then update the plugin:
/plugin update juan-workflow@juan-workflowRestart your Claude Code session after updating.
Requires:
- Claude Code with plugin support
- GitHub CLI (
gh) — authenticated- Linear MCP — connected to Claude Code
- jq —
brew install jq(macOS) orapt install jq(Linux)- Greptile GitHub App — recommended but optional
git clone https://github.com/DojoCodingLabs/juan-workflow.git
cd juan-workflow
# In Claude Code:
/plugin marketplace add .
/plugin install juan-workflow/juan-workflow:juan-is-working
Or with a task description:
/juan-workflow:juan-is-working add a search bar to the movie list page
- "What do you want to work on?" — Explain your task
- Duplicate check — Makes sure nobody's already doing this
- Spike — Brainstorm back and forth, document decisions in Linear
- Implementation — Create branch, code, lint, test
- PR — Push and wait for Greptile review
- Handoff — Assign a human reviewer, update Linear
For large tasks, the workflow will suggest using /feature-dev for the implementation phase. It handles everything before (spike, planning) and after (PR, review, handoff) — /feature-dev handles the actual coding.
juan-workflow/
├── .claude-plugin/
│ ├── plugin.json # Plugin metadata
│ └── marketplace.json # Marketplace catalog
├── commands/
│ └── juan-is-working.md # 🧠 The main orchestrator (all 7 phases)
├── agents/
│ ├── pattern-learner.md # 🔍 Discovers org patterns (Phase 0)
│ └── duplicate-checker.md # 🔎 Finds overlapping work (Phase 2)
├── scripts/
│ ├── wait-greptile.sh # ⏳ Polls for Greptile review (Phase 5)
│ └── assign-reviewer.sh # 🎯 Round-robin reviewer pick (Phase 6)
├── LICENSE
└── README.md
On first run, the pattern-learner agent analyzes your repo and Linear workspace:
- Branch naming conventions — analyzes 20+ recent branches to detect the pattern
- PR title format — learns from 10 recent PRs
- Team members — builds the reviewer pool from GitHub collaborators
- Linear workflow states — maps all states and their IDs
- Labels — finds the Spike label (and others)
- Greptile bot — detects if Greptile is configured and its username
Everything is saved to .claude/juan-workflow-learned.local.json (gitignored). Re-learned automatically if the config is older than 7 days.
After creating a PR, the workflow waits for Greptile:
- 6 minute initial wait
- 2 minute retry intervals
- 15 minute max wait
- If Greptile has feedback → address it, push, re-wait
- If 3 rounds without clean review → offer escape to human review
- If Greptile isn't configured → skip gracefully
Reviewers are assigned from the learned team pool in round-robin order. The index persists in the config file so it rotates fairly across sessions.
| Situation | What happens |
|---|---|
| Linear MCP unavailable | Warns, continues GitHub-only |
gh not authenticated |
Shows error, asks to run gh auth login |
| Greptile timeout (>15 min) | Asks: wait more / proceed / check manually |
| Config missing mid-workflow | Re-triggers Phase 0 |
| Branch name collision | Appends numeric suffix |
| Greptile loop >3 rounds | Warns, offers escape to human review |
| Juan says "stop" | Graceful exit, shows what was created |
| Tool | Required | Notes |
|---|---|---|
| Claude Code | ✅ | With plugin support |
GitHub CLI (gh) |
✅ | Must be authenticated (gh auth login) |
| Linear MCP | ✅ | Connected to Claude Code |
jq |
✅ | For scripts (brew install jq) |
| Greptile | 📋 Recommended | If not present, review gating is skipped |
/feature-dev |
📋 Optional | For large feature implementation |
- 🔔 Slack notifications on PR ready
- 📊 Cycle time analytics
- 🔄 Auto-resume interrupted workflows
- 👥 Team mode (not just Juan)
- 🤖 Greptile MCP integration (when available)
- 📦 Multi-task batching
- 📍 Review follow-up monitoring
This started as a joke plugin for one non-engineer. Now the whole team uses it. If you want to make it better:
- 🐛 Bug fixes — Found an issue? Open a PR
- 🔧 New phases — Got an idea for a workflow step? Let's talk
- 🌍 Translations — Help us add more bilingual touches
- 📝 Better docs — Always welcome
Dojo Coding Labs is a LATAM-first tech education and product studio. We build tools for developers and teach people to code.
juan-workflow is free forever. Open source. MIT licensed. If a Head of Product can ship code safely, so can you.
- CodeSensei — Learn to code while you vibecode
- VibeCoding Bootcamp — Structured curriculum with live mentors
- DojoOS — Full developer environment and community
MIT License — free to use, modify, and distribute.
🏗️ From product guy to shipping code — one /juan-is-working at a time.
Free. Open source. By Dojo Coding Labs.