The Problem That Started It All
this weekend I built something that i have found incredibly useful and productive: an automated pipeline for processing ideas into plans. It helps me to capture and process ideas that would have just sat in my email or notes and gone nowhere. now i can dictate the idea on my phone into Todoist, AI reads the todoist task notes and attachments, analyzes the idea, explores/expands on it, and creates plans that are saved as comments on the Todosit task – ready for me to review when i have time.
i have even extended it so that I can review the plans listed in the Todoist item and approve for implementation, so AI will start building the plans just by moving it into the “implement” section of the AI-inbox folder in Todoist. totally AFK (away from keyboard) and i dont have to sit in front of the computer and babysit it.
https://preview.redd.it/2gcbvbt4tyjg1.png?width=2018&format=png&auto=webp&s=3e83227702d33e6d3cbdefd0003fb3eb3437a5d4
https://preview.redd.it/zr5vj650zyjg1.png?width=1776&format=png&auto=webp&s=117fb31e0113eb190c9a17d2e3f36e8c2086fff9
I am happy to share more details if anyone’s interested. There are more than a few parts to configure, so not the simplest solution to setup, but i think its worth the effort.
onward… so the above is useful and interesting (I think), but this lead to another idea (so many ideas…) which i think could be even more powerful. see part2 below
Part2-the bigger, better idea
this system for processing ideas seemed like a no-brainer that it would be useful to others, and i was planning to share the solution, but then I tried to package it.
The Packaging Problem
Here’s what the AI Inbox actually is:
A Python watcher scripts that runs every 15 minutes (cron job)
Shell scripts hooked into my CLI toolchain
Todoist API integration (requires OAuth, API keys, project IDs)
MCP configuration wired to Claude Desktop
Folder structure that mirrors my codebase paths
Environment variables and more…
If I shipped this as an npm package or Python library, it would:
Fail on the user’s machine (wrong home directory path)
Require API credentials upfront (install/ configure friction)
Assume their cron is available (not on Windows)
Expect specific folder names that don’t match their setup
Break on probably any change, next reboot (too brittle).
I could add config files and template scripts and env vars and documentation. The result would be lots of complexity to do something that takes NN minutes to set up once you understand
what
you’re building.
The real problem:
I was trying to distribute
code
, but what I actually built was a
configured environment
. Those are not the same thing.
The Insight: Ship the Spec, Not the Code
What if I distributed the
specification
instead of the implementation?
Instead of “here’s my code, make it work,” I’d say: “Here’s what the system should do, step by step. You have AI. Build it.”
An AI agent could:
Adapt paths to the user’s home directory
Explain why each credential is needed
Handle OS-specific details (cron vs Windows Task Scheduler)
Let the user edit the requirements
before
anything gets installed
Know about their specific integrations (Slack vs Discord, Different task manager, etc.)
This is already how we build infrastructure. Terraform doesn’t ship a pre-built cloud. It ships a declarative spec, and you run it in your environment.
The idea:
Distribute solution blueprints (PRDs) instead of packages. Let AI do the local adaptation.
How It Works:
PRD.md
Format
A “PRD” in this context isn’t a product requirements document. It’s a
distributable solution specification
.
Here’s the structure:
ai-inbox/ ├── PRD.md # The blueprint ├── CUSTOMIZE.md # Guide for adapting it to your setup ├── scripts/ │ ├── ralph.sh # Autonomous execution engine │ └── digest.py # Helper scripts (optional reference) └── references/ └── api-keys.md # What credentials you need and where to get them
The
PRD.md
file contains:
Frontmatter
(YAML):
What this system does, who it’s for, complexity level
Prerequisites: “You need Python 3.8+, a Todoist account, Claude Code CLI”
Estimated build time, number of tasks, categories
User Configuration Section
:
Variables to customize before building: - TODOIST_API_KEY: Your API key (get it here: ) - PROJECT_DIR: Where to install (~Projects/ai-inbox) - DIGEST_TIME: When to send daily digest (07:00) - MCP_CONFIG_PATH: Your Claude Desktop MCP config
Task Breakdown
:
- [ ] US-001 Create Python watcher script (~20 min, ~60 lines) - [ ] US-002 Configure cron job (~5 min) - [ ] US-003 Integrate Todoist MCP (~15 min) - [ ] US-REVIEW-S1 Integration test 🚧 GATE Each task includes: Exact implementation steps Test-first approach (RED phase: write tests, GREEN phase: make them pass) Acceptance criteria: “Run X command, expect Y output” File paths (using the user’s customized variables) The Build Loop: Ralph You’d use it like this: git clone https://github.com/username/ai-inbox.git cd ai-inbox # Read the customization guide, edit the PRD with your values cat CUSTOMIZE.md $EDITOR PRD.md # Tell Claude to build it (with the Ralph autonomous loop) ./scripts/ralph.sh ai_inbox 20 2 haiku # Watch progress in real-time tail -f progress.txt Ralph is a simple loop: Read PRD.md Find the first unchecked task
- [ ] Execute it (Claude Code reads the implementation details, writes code, runs tests) Check it off:
- [x] Repeat No human in the loop. let it run and NN minutes later, you have a working system configured for your environment. Why This Is Better Than Packaging The Real Example: AI Inbox Here’s a real task from the AI Inbox PRD:
US-002: Configure cron job (~5 min) Implementation: - File: Add entry to user crontab - Command: PROJECT_DIR/scripts/watch.sh - Schedule: Every 15 minutes Approach: 1. Create log directory: mkdir -p PROJECT_DIR/logs 2. Edit crontab: crontab -e 3. Add line: */15 * * * * PROJECT_DIR/scripts/watch.sh >> PROJECT_DIR/logs/watch.log 2>&1 Acceptance Criteria: - Run: crontab -l | grep watch.sh - Expected: Shows your cron entry - Run: ls PROJECT_DIR/logs/watch.log - Expected: File exists and has content after 15 minutes
Every PROJECT_DIR is a placeholder. When you customize the PRD, you replace it with your actual path (e.g., /Users/yourname/projects/ai-inbox ). The AI agent reads the task, substitutes your values, and executes it verbatim. If you need Slack instead of Todoist, or Windows instead of macOS, or a different task manager? Edit the PRD before building. Delete the Todoist tasks, add Slack tasks. The AI doesn’t care — it just reads the spec. Why This Matters (Philosophically) Modern software is drowning in distribution friction . Package managers solved it for code , but not for systems . Terraform solved it for infrastructure specs Ansible solved it for configuration state Docker solved it for frozen environments But for complete, customizable systems that live in a user’s environment ? We’re still shipping monolithic packages and hoping. PRDs are the missing layer. They’re executable specifications. They’re AI-native because they assume an intelligent agent will interpret them. They’re user-friendly because humans can read and edit them. They’re composable because one PRD can depend on another.
I am curious what the community thinks. does this make sense or am I hallucinating that this is a problem, or maybe there is already a solution for this. assuming this is not already solved: Would you use a PRD instead of a distributed package? What system would you want as a PRD? submitted by /u/More-Journalist8787
Originally posted by u/More-Journalist8787 on r/ClaudeCode