Freelance Pipeline

An Obsidian plugin that turns a raw client conversation into a fully managed freelance project — and stops for your approval at every step.

The headline principle: the AI proposes, you approve. The plugin never creates, changes, or deletes a note in your vault without first showing you a preview and waiting for you to click Approve. You are the boss; the AI is the intern.

---

1. What it does

You paste a messy client chat into the plugin. From there it walks the project through six checkpointed stages, handing the work back to you between every one so you stay in control:

 You paste the client chat
          │
          ▼
 1. Intake      — the AI reads the chat (and any client files) and writes its first
          │        understanding as a DRAFT brief.
          ▼
 2. Alignment   — you correct the AI in the chat panel until you both agree, then LOCK the
          │        agreement as Brief.md. From here on, the locked brief is the single
          ▼        source of truth — later stages never re-read the raw chat.
 3. Prep list   — the AI proposes what to research and which tools to use; you approve.
          │
          ▼
 4. Research    — the AI works through the prep list, saving one note per finding.
          │
          ▼
 5. Planner     — the AI drafts Phases → Tasks; you approve, edit, or reject each task.
          │
          ▼
 6. Builder     — approved tasks run one at a time, test-first, with a plain-English diary.
          │
          ▼
        Done 🎉

Everything the plugin produces is ordinary Markdown living in your vault, so you can read, search, and edit it with the rest of your notes.

2. Install

From Obsidian's community plugins (once the plugin is accepted):

1. Open Settings → Community plugins → Browse.
2. Search for Freelance Pipeline, click Install, then Enable.

Manual install (works today):

1. Build or download the three files: main.js, manifest.json, styles.css.
2. Copy them into your vault at <your-vault>/.obsidian/plugins/freelance-pipeline/ (create that folder if it isn't there).
3. In Obsidian, open Settings → Community plugins, turn off Restricted/Safe mode if needed, and Enable "Freelance Pipeline".

This is a desktop-only plugin — the Builder stage runs test commands, which needs a real computer (Obsidian mobile can't do that).

3. Setup in 3 minutes

The plugin talks to an AI through a profile. A profile is just four things:

Field	What it means	Example
Name	A label for you	"Fast & cheap"
Base URL	Where your AI lives	https://api.openai.com/v1
API key	Your secret key (leave blank for local models)	sk-…
Model	Which model to use	gpt-4o-mini

Example base URLs for popular services:

Service	Base URL	Needs a key?
OpenAI	https://api.openai.com/v1	Yes
OpenRouter	https://openrouter.ai/api/v1	Yes
Groq	https://api.groq.com/openai/v1	Yes
DeepSeek	https://api.deepseek.com/v1	Yes
Ollama (local)	http://localhost:11434/v1	No (leave blank)
LM Studio (local)	http://localhost:1234/v1	No (leave blank)

Steps:

1. Open Settings → Freelance Pipeline.
2. Fill in a profile, then click Test connection — you want the green checkmark.
3. You can keep two profiles: an everyday one (used for chat and summaries) and a planner one (used for the heavier planning and building work). Pick which profile is which with the two dropdowns. If you only have one, set it as both.

If a call fails with a network or CORS error (common with some hosted proxies), turn on the profile's Compatibility mode (no streaming) toggle — it sends requests a slower but more compatible way.

4. A full walkthrough

Run commands from the command palette (Cmd/Ctrl-P, then type "Freelance Pipeline").

1. New project — creates a Projects/<name>/ folder with everything the pipeline needs.
2. Start / continue pipeline → Intake — paste the client conversation; the AI shows its first understanding and asks to save it as a draft brief.
3. Alignment — chat with the AI to fix anything it misread; when you're happy, click Agree — lock the brief and it writes the final Brief.md.
4. Lock — the locked brief is now the source of truth; the AI will never edit it on its own (unlock it by hand via the note's properties if you ever need to).
5. Prep list — the AI suggests research topics and tools; approve to save Research/Prep List.md with tick-boxes.
6. Research — the AI works through each unticked item and saves one note per finding, each needing your approval before it lands.
7. Plan review — the planner drafts Phases → Tasks; each task gets a review card (Approve / Edit / Reject / Decide later / Stop). One batch confirmation at the end writes every task note plus Plan.md at once.
8. Build — approved tasks run one at a time. For a code task the AI writes a small test (you approve it), the test must FAIL, the AI implements, and the test must PASS. Manual tasks (buy a domain, email the client) get a checklist and an "I did it" button. The whole story is logged in Logs/.

5. The vault structure

The plugin creates this layout inside your vault:

Projects/
  <project-name>/
    Project.md        ← project dashboard; records which stage you're on
    Brief.md          ← the locked agreement from Alignment
    Plan.md           ← the phases overview (from the Planner stage)
    Research/         ← one note per research finding
    Tasks/            ← one note per task
    Logs/             ← plain-English daily diary
    files/            ← client uploads, code exports, assets
Lessons/              ← shared lessons-learned notes across all projects

6. Power features

Each of these is a separate command — run it from the palette, pick a project, and go. None of them run while a pipeline step is busy.

• Scope-creep alarm — paste a new thing the client asked for, and the AI compares it to the locked brief, splits it into "already covered" vs. "extra (paid) work — about X hours", and drafts a warm, ready-to-send reply. You choose whether to save it.
• Exports — write a client-friendly Proposal.md from the brief and estimates (prices are left as a [your rate] placeholder — the AI never invents money), or a warm weekly update from the last 7 days of logs. Both preview before saving.
• Estimates roll-up — adds up every task's time estimate per phase and overall into a ## Estimates block in Plan.md (1 day = 8 working hours).
• Cost meter — every AI call quietly tallies tokens onto Project.md. "Show AI cost" reads them back in plain English; fill in the optional "Price per 1M tokens" boxes on a profile to also see an estimated dollar figure. Some local models don't report usage — the meter counts those calls and says so rather than pretending the total is complete.
• Lessons learned — distills a finished project into a short list of transferable lessons and saves it to the shared Lessons/ folder, which every future project's Research stage already reads.
• Explain-it-simply dial — set the Explanation level in settings to Beginner, Normal, or Expert. Every AI reply follows your choice, from spelled-out to terse.

7. Offline / local models

You do not need a paid cloud AI. The plugin works with a model running on your own computer through Ollama or LM Studio, so your client's words never leave your machine. See docs/OFFLINE.md for step-by-step setup.

8. ⚠️ Honest safety notes

Please read these — they're short and they matter.

• Your API key is stored in plain text. Like almost every Obsidian plugin, your key lives in <your-vault>/.obsidian/plugins/freelance-pipeline/data.json unencrypted. If you sync your vault to a public place (a public GitHub repo, a shared drive), exclude that file or your key could leak. If you use local models with no key, there's nothing to leak.
• The Builder runs real shell commands — but only ones you approve. During the Build stage the AI may need to run a command (for example, to run a test). It will always show you the exact command on a card first, and nothing runs until you read it and click Run it. Commands run inside the project's files/ folder and time out after two minutes. The AI can never write files outside that files/ folder — bad paths like ../ or /etc/... are rejected before anything is saved.
• The approval modals are the contract. When a preview or a command card pops up, that's your chance to catch a mistake. Read it before you click Approve or Run it.

The plugin's only network activity is the calls to the AI endpoint you configured in settings. There is no analytics, no telemetry, and no other "phone home".

9. For tinkerers

• npm run dev — build in watch mode (esbuild). Point it at a test vault: put the repo inside <test-vault>/.obsidian/plugins/freelance-pipeline/, then reload the plugin (or use a hot-reload plugin). Never develop against your real vault.
• npm test — run the automated tests (vitest). npm run build — type-check and produce a production main.js.
• PROGRESS.md is the project diary — a plain-English record of what each phase added.
• plans/ holds the build history: the spec (PROJECT-SPEC.md) plus one plan per phase.
• New feature ideas we deliberately parked live in docs/IDEAS.md.
• See CONTRIBUTING.md to get started contributing, and CHANGELOG.md for release history. Report security issues privately per SECURITY.md.

10. License

Released under the MIT License. © 2026 Teddy Jubu.

---

Freelance Pipeline is a working title. See PROGRESS.md for the current status.