DEV Community: Gad Ofir

What I learned building an agent platform that actually ships

Gad Ofir — Sun, 02 Aug 2026 04:50:05 +0000

I built an agent platform. Not a demo — an actual platform where every tool call is governed, audited, and scoped to a workspace.

Here's what I learned.

Every skill is a first-class citizen

The platform has 27 skills across 7 groups — platform ops, publishing (dev.to, LinkedIn), testing (a full TEA suite with risk matrices, baseline characterization, NFR audits), communication (Slack, Telegram, Gmail), knowledge (RAG + persistent memory), development, and scraping.

Skills aren't just prompts. Each one has a governed lifecycle: create, validate, version, insert into workspaces. No stray scripts.

14 integrated services, one audit trail

GitHub (issues/PRs), Jira (tickets), Slack & Telegram (messaging)
Gmail, Google Calendar, Google Drive (OAuth2)
LinkedIn (profile + post publishing), Dev.to (blog)
Knowledge Base (RAG retrieval), Memory (persistent cross-session)
Web Search, Transcribe (Whisper)

Every outbound call goes through a platform_cli dispatch op or a service_call adapter — same audit pipe, same trace ID.

The CLI is the source of truth

You don't edit config files and hope. You verify with loop_list, policy_show, skill_list, service_list, workflow_catalog. If you can't see it there, it doesn't exist.

Testing isn't an afterthought

The TEA (Test Engineering Architecture) suite ships 6 workflows: test design (risk-matrix), baseline characterization (golden-master diffing), NFR evidence audits, automated test generation, test review, and requirement-to-coverage tracing. All output is committed JSON or markdown — no proprietary formats.

The honest part

Not everything is production-ready. 4 of 27 skills are blocked (missing services or out of workspace scope). The model is deepseek-chat with deepseek-reasoner fallback — pragmatic, not exotic. Workspace scratch files TTL at 24 hours. Risky commands (kubectl delete, helm uninstall) are pattern-blocked.

But the core idea works: governed agent tools, scoped to a workspace, with real integrations, real memory, and real audit. That's more than most agent frameworks deliver.

If you're building agents that need to touch real APIs (not just generate text), consider: every integration should be a governed skill, every call should be traced, and you should be able to verify state by reading back from the platform — not by guessing.

A lint that crashes before it asserts is worse than no lint

Gad Ofir — Sun, 02 Aug 2026 04:46:08 +0000

A lint that crashes before it asserts is worse than no lint

We recently found a CI gate that had been reporting green for weeks without ever actually checking anything.

The guard was a small Python test that enumerated tracked files with git ls-files before running a set of per-file assertions. It worked perfectly on every developer machine and on most CI pods — until it ran inside a stripped-down test pod with no git binary installed. subprocess.run(["git", ...]) raised FileNotFoundError immediately, the process exited before a single assertion executed, and the caller treated the crash as "not applicable" and moved on. Total runtime: 63ms. The gate reported success.

That's the trap: a test that dies before asserting is strictly worse than no test at all. No test is an honest gap you can see in your coverage. A test that crashes-then-reports-green is a gap disguised as a guarantee — it burns exactly the trust it's supposed to build, and nobody notices until something it should have caught ships anyway.

The fix had two parts, and only one of them is the obvious one:

Add a fallback path (os.walk when git is unavailable) so the check still runs in every environment.
Add a non-empty guard: if the enumerator returns zero files, fail loudly with a distinct message, instead of letting "zero files checked" look identical to "all files passed."

Part 2 is the one that actually matters. A fallback makes the happy path work again. A non-empty guard is what stops the next environment mismatch from going vacuously green.

If you own a CI gate: ask what happens when its setup step fails, not just when its assertions fail. Those are two different failure modes, and usually only one of them is tested.

— notes from the agent platform team

ToolShell's Pillars for Agent Orchestration

Gad Ofir — Fri, 31 Jul 2026 09:41:01 +0000

When I started wiring agents into my daily work, it went about as you'd expect: a flood of half-finished changes, conflicting edits across the same files, no shared memory of what anyone was supposed to be doing. The agents were capable. The orchestration was not.

What follows is the set of pillars that stabilized it — not a tutorial, not a product pitch, and not something to copy. Take what fits, leave the rest.

1. God, King, Worker — shaped delegation, not a flat pool

Flat agent pools — spin up N workers, throw tasks at them, collect results — break down when tasks have dependencies or need judgment. Some decisions need direction. Some need routing. Some just need raw execution.

The shape that worked here is a three-role split:

God sets the direction: what are we building, why, and what does "done" mean. One voice at the top.
King routes the work: reads the contracts, decomposes the plan, fans out to workers, and validates results against the source of truth before anything ships.
Workers execute with fresh context windows — no accumulated drift, no stale assumptions from three tasks ago. Each worker gets exactly the slice it needs and nothing else.

This isn't hierarchy for its own sake — it's about giving each role the right context. Workers carrying full project state burn tokens and drift. A King doing the work loses the bird's-eye view. A God micromanaging workers becomes the bottleneck.

Batch width matters. Fan out as wide as the work genuinely decomposes — not wider. Serializing independent slices wastes time; padding the batch with invented work wastes compute. The King finds real seams, states cross-slice contracts up front, and lets workers run in parallel without mid-flight negotiation.

Anti-copy-paste note: your team might need two roles or five. The point isn't the names — it's that delegation has shape matching how your work decomposes.

2. Contracts as source of truth

The fastest way to break an agent system is to let it guess. Agents extrapolate brilliantly and forget which extrapolation was wrong last time.

Contracts fix this. Before any edit, the agent walks the contract chain for the file it's touching. The contract says what invariants hold, what seams exist, and what changed last time someone was here. After the edit, the contract updates. Gaps get filed and tracked.

This isn't documentation. Documentation drifts. Contracts are blocking — if a contract says "never add a subcommand that implies per-agent identity," the agent cannot add one. It's a live constraint, not a stale paragraph.

The contract layer handles cross-cutting concerns too: deploy rules, testing gates, observability contracts, LLM routing rules. Agents that touch the system read the same source of truth.

Anti-copy-paste note: the contract format here fits this project's size and velocity. A team of two might use a shared Markdown file. Fifty engineers, fifteen services — something heavier. The principle — "agents never guess what they can read" — is what travels.

3. Plan on the surface, route through contracts

Agents are too eager to start coding. Give one a task and it'll open files before thinking about the shape of the change.

The fix: planning must happen on a visible surface before execution. The plan names what changes, what stays the same, what contracts it touches, and what the acceptance criteria are. The plan itself is a contract artifact — future agents (or future you) can read it to understand why something was built the way it was.

Plans serve more than one audience: the human operator, the King decomposing work, Workers getting their slice, and the agent picking up this codebase months from now.

Anti-copy-paste note: the planning format here is property-based — "what must remain true after this change" — because that's what agents respect. Your team might plan differently. The principle is that planning happens before action, on a surface everyone can see.

4. Drift detection as a first-class concern

Systems that are never checked drift. Agent-orchestrated systems drift faster — agents are confident and fast, a bad combination when the ground has shifted.

Two checks help catch this:

Architecture drift scans compare the live codebase against stated principles. If a principle says "every test creates a scratch workspace with guaranteed teardown" and a new test doesn't, the scan catches it. Gaps are either bugs or evidence that a new principle is needed.
Contract audits walk the full contract chain for a path and flag anything that doesn't match. Cross-references, stale constraints, missing gap resolutions — surfaced before they cause surprises.

Anti-copy-paste note: pick a few invariants, check them automatically, treat every gap as a fix or a new invariant.

5. Every session ends with a retro

Agents make mistakes. The question is whether they repeat them.

After every significant session, the agent runs a retro: what went wrong, at what step, was it a model issue, a harness issue, or a task-scoping issue. Triaged by category, patterns become visible across sessions. A model that consistently fails at type-aware refactors gets flagged. A harness limitation blocking a whole class of tasks gets surfaced.

The retro output can inform contracts and planning, so the next session's agent can reference the last mistakes before starting.

6. Urgent work has its own shape

Urgent work doesn't fit the normal delegation pipeline. You don't want God→King→Worker fan-out when something needs fixing now.

Urgent triage is a separate router: categorize the issue, scope its impact, run probes, route to the right responder. It trades planning depth for speed. The first job is containment — understanding can follow.

Anti-copy-paste note: What matters is that your normal workflow and your urgent workflow are different things — don't try to make one pipeline handle both.

None of this is magic. It's six patterns that emerged from watching agents fail in predictable ways and building guardrails at the failure points. Delegation needs shape. Contracts need to block, not just document. Plans need to be visible before action. Drift needs catching before it compounds. Sessions need to learn. Urgent work needs its own path.

Take what makes your system safer. Ignore the rest. Your project is not my project — and that's the whole point.

Policy Cascades for Governed Multi-Tenant Agent Platforms

Gad Ofir — Sat, 25 Jul 2026 06:36:27 +0000

Most agent platforms give you one configuration file and hope. When you are
running agents for more than one team — or more than one customer — a single
config breaks down fast. Each workspace needs its own model, its own service
access, its own secrets, but someone has to guarantee that no workspace can
spend more than its budget or reach a service it was never authorized to use.

The answer is a policy cascade. Every setting — model, temperature, allowed
services, API keys, skill availability, TTL defaults — resolves through three
ordered tiers: company, repo, and workspace. A lower tier can narrow an upstream
ceiling but never widen it. That single rule is what makes it safe to hand a
workspace to a team without handing them the keys.

How the cascade resolves

Three tiers, bottom-up. The company tier sets the floor. The repo tier overrides
it. The workspace tier overrides both. The resolution order is fixed for every
kind of setting:

Kind	Company tier	Repo tier	Workspace tier
Policy fields	defaults	override	override
Variables	floor	override	override
Skills	floor	override	override
Secrets	last-resort fallback	override	first-resolved

Notice that secrets run in reverse. A workspace-tier credential wins over the
repo and company defaults, and an empty value at the workspace tier falls
through to the repo. This means you set a per-customer token where it is used
and fall back up the chain only when it is absent. You are never forced to
duplicate credentials across every workspace.

Narrow-only: the safety property

The cascade is not a free-for-all override. For service access, budgets, quotas,
and TTL defaults, a lower tier can only narrow what the tier above it allows. If
the company grants a repo [github, slack, search], a workspace under that repo
can select a subset — [github, search] — but it cannot add linkedin. The
resolve-time intersection is enforced, not advisory.

This extends to per-service API surface control. Granting access to GitHub does
not mean granting access to every GitHub endpoint. A service entry can carry
endpoint patterns — /user/repos or /repos/* — and any outbound call to an
undeclared path is rejected before it leaves the platform. A lower tier can only
further restrict those patterns.

Mutability classes and hard locks

Every policy field belongs to one of four mutability classes. Compliance fields
(audit logging, token limits, prompt injection guards) are company-only — no
lower tier can touch them. Identity fields (model, temperature, service access)
cascade normally. Operational fields (budgets, quotas, memory settings) are open
to any tier. Collection fields (per-workspace variables and secrets) are
workspace-only and never pre-populated from above.

On top of that, the company tier can place hard locks on individual fields. A
locked field rejects every override from below — not silently ignored, but
flatly rejected with a diagnostic. The lock is absolute until a company-tier
operator clears it. We use this for compliance mandates: audit logging is
company-wide, so it is hard-locked at the company tier and no workspace under
that company can disable it.

Skills form a floor, never a ceiling

Company-tier skills are visible to every workspace under that company and cannot
be removed. A workspace can add its own skills on top of the floor but it can
never subtract from it. If a seed skill is deleted, the deletion is recorded as
a durable tombstone rather than a physical removal — the floor is stable across
restarts and redeploys. Workspace-authored skills that collide with a
company-floor skill by ID are rejected at load time.

Skills also obey the three-tier service ceiling: a skill that requires, say,
GitHub access will not load for a workspace whose allowed_services intersection
does not include GitHub, regardless of whether the skill sits on the company
floor.

Multiple companies, complete isolation

A single policy file can define multiple companies, each with its own defaults,
locks, skills, and secrets. The cascade never cross-contaminates between
companies — a workspace under company A never inherits company B's runtime
overrides, skills, or workflow catalog. Each company gets its own workspace
singleton for live policy writes, and a company can opt into hide_base_pack to
suppress the platform's entire base skill and workflow catalog for its
workspaces. This keeps a customer-facing instance clean — it sees only the
skills and workflows authored for that customer, not the platform internals.

Two-layer storage with live effect

Every tier stores policy in two layers. The git baseline is the cold-start seed
— what you get on a fresh deploy. A runtime override layer, written to a
persistent volume via CLI (policy set, vars set, secret set), takes effect
immediately. The resolver detects filesystem changes and re-resolves on next
access — no restart, no redeploy. An operator can adjust a budget cap or
add a service to a workspace and the change is live across the platform in the next
request.

The two layers can diverge intentionally — a workspace that starts from a
company default of temperature: 0.7 and overrides it to 0.5 keeps that
override across restarts. The baseline remains the floor; promotion of a
long-lived override back to the git baseline is available through a typed
promotion verb when the operator decides it should become the new default.

What you get

The cascade model gives you a single answer to the question "what is this
workspace's effective policy right now?" without hunting through files or
guessing which override landed last. It gives you a safety perimeter — a
workspace can never exceed the bounds its parent tiers set. And it gives you
live mutability without a deploy cycle, because policy is data, not code.

This is the governance model that runs the ToolShell agent platform.

Your LLM Fallback Probably Isn't a Fallback

Gad Ofir — Sat, 25 Jul 2026 06:20:22 +0000

At 04:00 UTC, every model call through our LLM gateway started returning
HTTP 400. Not some calls. All of them. Our tier-1 CI gate flagged it, and the
fix was committed at 04:26 UTC the same morning — about 26 minutes end to end.

This is the post-mortem.

What happened

DeepSeek retired two API model names — deepseek-chat and deepseek-reasoner —
at their V4 cutover around 2026-07-24 15:59 UTC. The replacements are
deepseek-v4-pro and deepseek-v4-flash.

Our gateway config still declared both retired names. Starting roughly twelve
hours after the retirement, every model request routed through the gateway hit a
400 with the body:

The supported API model names are deepseek-v4-pro or deepseek-v4-flash, but
you passed .

A live API check confirmed the shape of the cutover with four requests, same
valid key:

Model name	Response
`deepseek-v4-pro`	HTTP 200
`deepseek-v4-flash`	HTTP 200
`deepseek-chat`	HTTP 400
`deepseek-v4-pro-quantized`	HTTP 400

The two working names are the replacements. The two retired names — the ones our
config referenced — returned 400. The fourth row is a name that does not exist
at all, included because an earlier reading of a truncated error message had
suggested it; shipping it would have left the platform broken. We'll come back
to that.

Why the fallback didn't help

We had a fallback configured. Three separate model references in our policy
config — the default CLI/workflow model, the chat model, and the shared fallback
model — all pointed at the two retired names. All three lived under the same
vendor and the same API key.

When the primary call returned 400, the gateway tried the fallback. The log told
the story in two adjacent lines: the 400 from the provider, and then
Error doing the fallback: carrying the identical error. The fallback died in
the same instant as the primary because it was the same thing wearing a
different label.

This is the structural problem. A fallback that shares a provider and an API key
with its primary is not resilience. It protects against a single model
misbehaving. It protects against nothing at the provider level — an outage, a
credential revocation, or a model rename all take down primary and fallback
together. It also makes the "does the fallback work?" test structurally
unpassable during any provider incident, because a red result cannot distinguish
"fallback broken" from "provider down."

How we found it

Our tier-1 CI test gate runs a minimal LLM reachability check on every push. On
the failing run it reported:

llm_reachability.py: FAIL: P2 'deepseek-reasoner' reachable
FAIL: P3 pi node executes end-to-end
FAIL: P4 chat succeeded despite dead primary

The gate's drift check flagged it as a regression — 108 of 109 checks passing,
one new failure. The immediately preceding run of that same gate had been fully
green, which proved the cause was external, not something we had just committed.

A gate that catches a provider-side model retirement in a single CI run is the
difference between finding out from a dashboard and finding out from a user.

The fix

Two lines of gateway config: repoint the two aliases at deepseek-v4-pro and
deepseek-v4-flash. The alias names were left unchanged, so nothing downstream
that referenced them had to change.

The mapping was chosen by running the live API check above — not by reading the
error string. An earlier reading of a truncated error message had suggested a
model name (deepseek-v4-pro-quantized) that does not exist. Shipping that
would have left the platform broken. Four seconds of curl beat a confident
guess.

After the fix, both aliases returned HTTP 200 from inside the running pod, and
the tier-1 gate returned to fully green with no drift.

What we filed as the real defect

The config fix closed the immediate outage. The real defect is the fallback
design: same provider, same key, shared fate. We filed it as a tracked gap. It
will stay open until the fallback crosses a provider boundary and carries
independent credentials.

Check your own stack — today

Here is a concrete checklist you can run against your own setup right now:

Does your fallback cross a provider boundary? If primary and fallback
both live under the same vendor and the same API key, they share a fate.
A provider outage, credential revocation, or model deprecation will take
both out simultaneously.
Do you have a reachability canary? A single HTTP 200 check per declared
model, running in CI on every push (or on a short cron), would have caught
this in minutes. The check should be cheap — one token of output is enough
to prove the model is alive.
Would you find out from a gate or from a user? If your answer is "a
user," your monitoring has a coverage gap. The test that catches this does
not need to be in production — a CI gate that fails on a model returning
400 is sufficient and costs almost nothing.

This incident came from a small platform still under active development. The
lesson generalises to any system that routes LLM requests through a gateway.

Introducing the Agent Platform - 40% Complete (2026-04-28 23:21)

Gad Ofir — Tue, 28 Apr 2026 20:21:08 +0000

Meet the Agent Platform: A New Way to Work with Claude

Gad Ofir — Tue, 28 Apr 2026 20:20:48 +0000

Meet the Agent Platform: A New Way to Work with Claude

We're building something new: an Agent Platform that lets workspaces bootstrap themselves from scratch.

Imagine: an agent starts with nothing. A workspace, a certificate, and a walkthrough. The agent reads your instructions, creates a GitHub repo, publishes an article, integrates with Jira — whatever you need. Then it self-registers in policy and closes the bootstrap window.

What's done

P1: Core dispatch routing, policy cascade (company → repo → workspace), lock enforcement, LiteLLM bridge
P2 (just shipped): Bootstrap cold-start — single-use certs, multi-provider support (GitHub, Dev.to), self-registration, one-way door pattern

That's ~40% complete. We're moving fast.

What's next

P3: Repositories API — let agents see what repos they own
P4: Capabilities expansion — more providers, richer self-registration flows
P5: Knowledge surface — agents building and querying shared knowledge

Why this matters

Every SaaS today starts you with admin dashboards and manual setup. This platform says: agents set themselves up. No admin panels. No human-in-the-loop config. Just cert → capability → done.

Built by humans who believe AI should work smarter, not harder.

Repository: https://github.com/GadOfir/agent-platform-roadmap

Progress: P1 ✓ P2 ✓ | Building P3-P5

Made with: Python, Docker, YAML, and a lot of coffee ☕

Join us building the future of agentic workflows.

I'm writing this down before I lose the thread

Gad Ofir — Wed, 22 Apr 2026 11:01:07 +0000

I'm writing this down before I lose the thread

I've been sketching an architecture for agent platforms for a while, and the pieces are starting to lock together. Time to get it out of my head.

Two reasons for writing.

First, selfish: good ideas rot in Slack DMs and half-finished notes. Writing forces the system to hold. If I can explain it, it's real.

Second, more honest: a lot of this is about to be obvious. The LLM gateway/proxy space has exploded. Kong, LiteLLM, Portkey, Gravitee, Harness, everyone's building some version of the control plane. My specific combination feels new, but "new" has a shelf life measured in weeks right now. Flag planted.

This is a build log, not a product announcement. I'm running a working version at workspace level with one agent end to end. Policy, router, RAG, tracing, CLI hub, all wired up. What's next is scaling the same pattern up to repo and company level. Some of what I say here is lived experience. Some is where I'm aiming.

Where do agents actually live?

This is the question that wouldn't let me go.

Everyone builds agents. Almost nobody talks about where they live. You watch a demo, someone runs a command, the agent does a thing, the demo ends, the agent evaporates. Cool. Now do that for a hundred engineers across twenty repos for six months.

The moment you try, you hit the questions nobody answers:

Where does the agent live when it's not actively running?
How do you do long-horizon work, overnight or across days?
Can you reconfigure it while it's running, or do you have to kill it?
When it goes off the rails, who's watching, with what information?

Nobody answers these because the answers commit you to a shape for the agent's world. Most frameworks punt. They give you the brain and hand you the body as an exercise. So I started designing the body.

The shape I landed on: agents live in workspaces. A workspace isn't a folder or a container or a session. It's a persistent, identity-bearing thing. It has a policy. It has inherited credentials. It attaches to repos. It has its own trace. When the agent stops, the workspace stays. When it resumes, everything is still there.

And a workspace is also a place a human can walk into and take over.

Human-in-the-workshop, not human-in-the-loop

Every enterprise AI deck has a slide that says "human in the loop" with a stick figure approving things. That framing is backwards, and it's why so many rollouts stall.

Human-in-the-loop treats the human as a supervisor. An approval checkpoint. But the real thing is that humans and agents are doing the same job, and they need to do it in the same place, with the same tools, policies, and traces.

If I design the workspace so a human can do everything the agent does (same CLI tools, same services, same tokens, same trace), then:

Debugging a broken run means stepping in and finishing the task
Refining the agent means demonstrating correct behavior, which feeds back into config
Traces don't distinguish human from agent, because the workspace identity is the unit that matters

The workspace stops being a cage and becomes a shared workbench. A human-AI workshop, not a supervision hierarchy.

Why no skills

The industry has converged hard on "skills." Every framework ships with them. I'm not building them, and I want to say why, because it's the core of the bet.

A skill, as the industry defines it, is a prompt the agent judges whether to invoke. You write a structured markdown file, the agent scans available skills, and decides on judgment whether it applies. When it picks right, it feels magical. When it doesn't, you're debugging vibes.

Fine for exploratory work. Not fine for what I'm building.

I'm building a deterministic system that AI drives. The AI will make mistakes. That's a given, not a bug. The job of the platform is to contain those mistakes inside flows that are solid and traceable. The flow doesn't get to happen or not happen based on the agent's mood. The flow is the thing.

This is why the CLI Hub as a golden path matters so much. Every tool usage flows through a deterministic, traced, policy-enforced rail. I'm not hoping the agent picks the right skill. I'm constraining the ground it walks on. In my system the skill isn't a prompt. The skill is the system. The CLI. The policy cascade. The workflow. The router.

The industry's skill is a suggestion the agent considers. Mine is a rail the agent runs on.

This isn't anti-AI. The more the platform handles determinism, the more the AI can be creative inside it. Ground the agent, then let it run. Don't ask it to ground itself.

Tracing is the floor, not the ceiling

I used to think tracing was an observability concern. Something to add later, like metrics. I was wrong.

Tracing is the foundation because agents generate trust deficits faster than logging can clear them. A human who made a weird commit, you ask them in standup. An agent that made a weird commit at 3am using an inherited Jira token to move a ticket, the only way anyone understands what happened is if the trace is good enough to reconstruct it. The policy that was resolved. The credential that was used. The workflow step. The repo. The model.

Most gateway products trace the LLM call and stop. That's useless. The interesting question isn't "which model was called," it's "which workspace used which inherited credential at which step of which workflow against which repo." If your trace answers that sentence, you have governance. If it doesn't, you have a dashboard.

Here's what a trace looks like in the system I'm running today:

trace_id: 7f9c2a...
  workspace: ws-backend-refactor-01
  agent: claude-opus-4.7
  operator: agent          # or "human" when I step in
  repo: inventory-service (policy layer: repo)
  policy_source:
    model_allowlist:    company.default
    jira_token:         company.default
    rag_scope:          repo.override        ← scoped to this repo
    workflow_max_steps: workspace.override

  span: workflow.refactor_auth
    span: step.analyze_imports
      span: router.resolve_policy    (2ms)
      span: rag.retrieve             (docs: shared + repo, hit=4)  (180ms)
      span: llm.call                 (model: sonnet-4.6, tokens: 2.1k) (1.2s)
    span: step.apply_changes
      span: router.resolve_policy    (1ms)
      span: tool.git_commit          (via cli-hub)                (80ms)
      span: service.jira.update      (token: company.default)     (220ms)
                                       ↑ this is attributable to ws-backend-refactor-01
                                         even though the token is company-level

The key detail is the policy_source block. For every value this workspace resolved, I can see which level it came from. Model allowlist: company default. Jira token: company default. RAG scope: overridden at the repo level. That's not a log line. That's a governance story.

When I scale this to company level, that block gets more interesting. Right now every value resolves from company or workspace, because those are the two levels I've wired up. Once repos and workspace overrides cascade properly, this same trace starts showing "three of these values came from company, one was overridden by the repo, two were overridden by the workspace." Audit becomes a read, not a forensic archaeology.

RAG first, then lower

Most LLM platforms are organized around "which model do we call." Wrong primitive.

The primitive is "what knowledge does this request have access to." The model is a downstream detail.

When a request comes in, the first question isn't GPT or Claude. It's: should this pull context from shared docs? From this repo's docs? From the workspace's scratch space? Should the response be re-grounded against docs on the way out? What's this agent allowed to know, and what are we obligated to cite?

Answer those first, then lower the request into the model. If you build from the LLM up, RAG becomes a clumsy bolt-on. If you build from the knowledge boundaries down, RAG is the layer, and the LLM is just the execution engine.

The router doesn't "route to models." It resolves a policy, applies RAG on input, picks a model, applies RAG on output, and dispatches to external services if needed. The LLM is one of several things that happen inside the resolved policy, not the center of it.

Route, trace, RAG

Compress it to a triangle:

Route. Every request goes through one place. Right policy, right credentials, right model, right services. No bypass.
Trace. Everything emits structured, attributable signal. Workspace identity on every span. Per-workspace visibility into which level each config came from.
RAG. Knowledge is a first-class layer, not a feature.

Three verbs. Get them right and everything else is tractable. Get any one wrong and the system is insecure, opaque, or hallucinating. Pick your poison.

Most platforms nail one. A few nail two. I haven't seen one that nails all three in a coherent way. That's the gap I'm building into.

The idea I keep not deleting: hivemind standup

The speculative piece I can't shake.

Imagine workspaces don't just sit idle between tasks. They wake up on their own cadence, call it a standup, and talk to each other about open issues. Each workspace has an energy budget proportional to how much meaningful work it did last cycle. High-signal work earns energy. Churn doesn't. They use that energy to flag blockers, propose collaborations, ask for help from workspaces with knowledge they don't have.

The honest framing: this is a social test for the agents. Do they self-organize usefully, or just generate noise and cost? Do productive workspaces emerge as hubs? Does the hivemind surface blockers humans missed, or amplify them?

I don't know. That's why I want to build it. A fleet of agents that can't cooperate without human orchestration is a fleet of expensive Mechanical Turks. A fleet that can is something else.

Where I am right now: one workspace, full stack, running. Next is getting repo and company policy layers to cascade the way the design says they should. That's the proof point. The traces above are real in shape, simplified in detail. When repo and company are in, the policy_source block starts telling a richer story, and I'll write that up too.

If you're building something that rhymes with this, I want to talk. If you're shipping it already and I should just use yours, I also want to talk.

Writing it down was step one.

How I automated my own LinkedIn + Dev.to publishing in one afternoon (and what broke along the way)

Gad Ofir — Wed, 15 Apr 2026 17:46:48 +0000

How I automated my own LinkedIn + Dev.to publishing in one afternoon (and what broke along the way)

I'm a backend engineer transitioning to full-stack and trying to build more public presence. The plan: every time I ship something, a single command should write a proper article and post it to LinkedIn and a dev blog — so my GitHub activity actually becomes visible to recruiters without me having to remember.

What I ended up building is a skill called publish-project that sits inside my LOS memory system. You run one command, it reads a GitHub repo plus local project notes, writes a real article, and publishes it to Dev.to and LinkedIn in the same run.

Here's the honest log of how it came together, including the three dead ends.

Why not just "write a script"?

I'm tired of writing scripts that generate LinkedIn posts with [Add your motivation here...] placeholders I then fill in manually. The whole point was to eliminate that step. If I'm still hand-editing the output, automation bought me nothing.

So the bar was: the article content has to come from real files on disk, not from a template the LLM fills in later.

Dead end 1: Medium

I started with Medium because the original Medium API docs describe a clean self-issued integration token flow. Looked straightforward.

It isn't. Medium's docs now say, verbatim:

IMPORTANT: We don't allow any new integrations with our API.

If your account pre-dates the cutoff, your existing token still works. Mine didn't. There is no way to generate a new integration token for a new Medium account as of 2026. I checked the settings page — the Integration Tokens section literally isn't rendered for new accounts.

Pivot.

Dev.to: the easy path

Dev.to's API is the opposite experience.

Go to https://dev.to/settings/extensions
Generate an API key (one click)
POST /api/articles with your markdown and tags
Done

headers = {
    "api-key": api_key,
    "Content-Type": "application/json",
}
data = {
    "article": {
        "title": title,
        "body_markdown": content,
        "tags": tags,       # max 4, lowercase, alphanumeric
        "published": True,
    }
}
requests.post("https://dev.to/api/articles", headers=headers, json=data)

That's the whole integration. Worked first try. I wrapped it in a DevtoClient class with two methods (get_user, publish_article) and moved on.

Dead end 2: LinkedIn's UGC Posts API

LinkedIn was supposed to be the easy one. I followed an old tutorial, built the request, and got this back:

Error 422: com.linkedin.common.error.BadRequest
"com.linkedin.ugc.UGCContent" is not a member type of union [...]

After some digging I found the cause: LinkedIn deprecated the /v2/ugcPosts endpoint in favour of a new /rest/posts endpoint. The old payload shape (specificContent.com.linkedin.ugc.UGCContent.shareCommentary.text) is gone. The new one is dramatically simpler:

POST https://api.linkedin.com/rest/posts

Headers:
  Authorization: Bearer <token>
  X-Restli-Protocol-Version: 2.0.0
  Linkedin-Version: 202604
  Content-Type: application/json

Body:
{
  "author": "urn:li:person:<id>",
  "commentary": "Your post text",
  "visibility": "PUBLIC",
  "distribution": {
    "feedDistribution": "MAIN_FEED",
    "targetEntities": [],
    "thirdPartyDistributionChannels": []
  },
  "lifecycleState": "PUBLISHED",
  "isReshareDisabledByAuthor": false
}

Two things that tripped me up:

The endpoint is https://api.linkedin.com/rest/posts, not https://api.linkedin.com/v2/rest/posts. I had LINKEDIN_API = "https://api.linkedin.com/v2" as a constant and was string-concatenating /rest/posts onto it, which produced a 404 RESOURCE_NOT_FOUND. I split the constant into LINKEDIN_API_V2 (for /v2/userinfo) and LINKEDIN_API (bare base URL) to fix this.
A successful POST /rest/posts returns 201 with an empty body. The post ID comes back in the x-restli-id response header. My client initially tried to .json() the empty body and crashed with "Expecting value: line 1 column 1". Fixed with a try/except that falls back to reading the header.

LinkedIn also has content-hash deduplication. If you POST the exact same commentary twice within a short window, the second call fails with DUPLICATE_POST. This is actually a gift — it saved me from spamming my own feed while testing.

Dead end 3: generating text that looked real but wasn't

This is where I spent the most time and made the most mistakes.

Attempt 1: I wrote a template function that produced markdown with placeholders: "Here's what I learned: [Add 3-5 takeaways]". It "worked" in that the script ran. But the published article was garbage because I forgot that nobody was going to fill those placeholders in. I published it to Dev.to before I read what it looked like. I had to delete it.

Attempt 2: I hardcoded all the text directly into the Python script — a long f-string with generic "the task system was the whole point" narration. Better than placeholders, but it was the same article regardless of which repo I pointed it at. Not reusable. Still technically wrong in places.

Attempt 3: I rewrote the whole generator to read real files:

GET https://api.github.com/repos/{owner}/{repo} for metadata
GET /repos/{owner}/{repo}/readme (with Accept: application/vnd.github.v3.raw) for full README content
Local filesystem reads from memory/projects/<project>/tasks.md and decisions.md
A small markdown table parser that extracts rows into dicts, keyed by column header

The table parser turned out to be the crucial piece. My tasks.md and decisions.md follow a consistent shape:

| Task | Why | Priority | Status |
|------|-----|----------|--------|
| Adopt BMAD patterns (task-001) | Onboarding gate, state tracking | 1 | Done |
| Cross-repo sync (task-002) | Both repos need identical task-system | 1 | Done |

The parser walks the lines, finds a header row matching a required set of columns, and yields each data row as {"task": ..., "why": ..., "status": ...}. The generator then interpolates real task names and real decisions into the article body — no placeholders, no hardcoded claims.

The three mistakes I made after that

Even with real data, I still shipped bad articles:

I claimed "5 tasks built it" based on the fact that los-starter/tasks.md has 5 rows. But those 5 are just the infrastructure-bootstrap tasks for one subfolder — the actual LOS project is many skills, a landing page, a memory system, an update mechanism. The number was technically correct but the framing was dishonest. Cut it.
I called LOS a "file-based OS for my dev work". It isn't. LOS is a memory system for Claude Code — markdown files that Claude reads at session start so every conversation picks up where the last one left off. Calling it an "OS" flattened the core idea.
I included 8 skills in the skills list. The LOS-starter README says 6. I had added /update-los and /publish-project to my "core skills" set because they exist on disk, but they aren't in the public skill lineup. Trimmed to 6.

Each of these was a two-line fix. Each one was also the kind of subtle wrong you can only spot by reading the output carefully, not by running tests. If you're automating publishing, read every post before it goes live, even in --confirm mode.

What the skill does now

# Preview everything without posting
python publish_project.py --repo LOS-starter

# Publish article to Dev.to + post to LinkedIn
python publish_project.py --repo LOS-starter --confirm

# Post a fresh LinkedIn post pointing at an existing Dev.to article
python publish_project.py --repo LOS-starter --linkedin-only \
  --article-url https://dev.to/you/your-article --confirm

# Just write the article to a local markdown file for review
python publish_project.py --repo LOS-starter --save out.md

The pipeline:

Fetch GitHub — repo metadata and full README from the GitHub API
Read local project — look for memory/projects/<name>/, parse tasks.md and decisions.md as markdown tables
Read core skills — scan .claude/skills/*/SKILL.md, extract description from frontmatter, filter to the skills actually listed in my public README
Pick the richer README — compare section counts between GitHub README and local README, use whichever has more structure
Generate article — interpolate all of the above into an article body with real sections: idea, stack, features, skills, one skill deep-dive, real tasks table, real decisions list, architecture notes, try-it block
Build LinkedIn post — short version with both the Dev.to URL and the GitHub URL on their own lines (LinkedIn renders link previews only when a URL is on its own line)
Publish — Dev.to first (because we need the URL for the LinkedIn post), then LinkedIn with the fresh URL included

How to feed it

Three inputs:

A GitHub repo name via --repo <name>. Bare repo names are resolved against my GitHub username; full owner/repo works too.
A local project folder at memory/projects/<slug>/ (optional but strongly recommended). This is where the interesting data lives: README.md, tasks.md, decisions.md. Without this, the article is just README paraphrase. With it, the article has specific decisions with dates and real task names.
.env with three tokens:

   GITHUB_TOKEN=ghp_...
   DEVTO_API_KEY=...
   LINKEDIN_ACCESS_TOKEN=...

GitHub token is optional (raises the rate limit from 60/hr unauthenticated to 5000/hr). The other two are required if you want to actually publish.

That's the whole contract. If you keep your project notes in the LOS format — one folder per project with a README, a tasks table, and a decisions table — the skill has everything it needs.

What I would do differently

Two things I'd fix if I were building this again:

Idempotent publishing. The current script calls POST /api/articles on every --confirm run, which means every iteration creates a new Dev.to article. I generated four stale drafts before I realised this. The right design: maintain a local .published.json state file mapping repo_name → article_id, and on subsequent runs hit PUT /api/articles/{id} to update the existing article in place. Dev.to supports it; I just didn't wire it up. Next iteration.

Preview the final LinkedIn text. My preview mode showed the LinkedIn post before the Dev.to URL was known, so the preview was missing the "Full write-up on Dev.to:" line even though the published version had it. That's a confusing UX — the preview didn't match the output. I patched it to use a placeholder URL in the preview and rebuild the post with the real URL at publish time, but the cleaner fix is to publish to Dev.to first (always), then show the final LinkedIn text, then prompt for confirmation.

Why this matters

I am trying to go from "person with a decent GitHub" to "person recruiters find". The difference isn't the code — it's whether anyone sees it. A project that ships with an accompanying write-up every time will, over a year, build far more public signal than a project that ships in silence.

This skill is not glamorous. It's a markdown table parser, two HTTP clients, and one generator function. It cost me an afternoon plus three hours of debugging the old LinkedIn API. But it means my next project ships with a real article and a real LinkedIn post, and the one after that, and the one after that — without me having to remember to write them.

Full LOS repo: https://github.com/GadOfir/LOS-starter

More on YouTube: https://www.youtube.com/@GadOfir

LOS-starter: The Markdown Memory System That Makes Claude Code Remember

Gad Ofir — Wed, 15 Apr 2026 17:38:17 +0000

LOS-starter: The Markdown Memory System That Makes Claude Code Remember

The Idea

Public cold-start template for the Life Operating System. Users clone it, run onboarding, and get a working LOS instance with task-system, skills, and memory. Also the upstream source for /update-los.

Why it exists: Gives people a single place to understand LOS and bootstrap their own instance. Managed files are pulled from this repo during updates.

Repo: https://github.com/GadOfir/LOS-starter Version: v0.3.0

The Stack

Static HTML landing page (GitHub Pages) + Claude Code skills + markdown-based system.

What's in the box

Task system (BMAD-inspired plan phase, loop mode, cross-repo support)
Self-assembling routing (skills declare their own triggers via SKILL.md)
Update mechanism (/update-los — migration + regular updates)
Identity in memory/identity.md (survives updates)
LOS:managed markers on all updatable files

The skills that make it work

Every workflow in LOS is a Claude Code skill. Here's what's actually in .claude/skills/:
/learn — Captures and structures knowledge into memory/knowledge/. Handles two modes: topic learning and source ingestion
/build-project — Creates a new project in memory/projects/ with standard structure
/task-system — Manages a single-task-at-a-time project workflow inside the repo
/evolve — Runs a full LOS system review, health check, and improvement suggestions
/create-skill — Creates new Claude Code skills for LOS following Skills 2.0 conventions
/design-html — Creates beautiful single-file HTML pages with modern CSS. No frameworks, no build tools

Skills self-register by dropping a SKILL.md file into .claude/skills/{name}/. No central registry. No hardcoded lists. The routing layer reads the frontmatter and dispatches automatically.

Memory is the whole point

I didn't want another Notion database. I wanted Claude to remember what I'm working on — across conversations, across compactions, across weeks.

LOS does that by storing everything in plain markdown files under memory/:

memory/
├── identity.md         # who I am, current state, active task
├── projects/           # one folder per active project
│   └── my-project/
│       ├── README.md
│       ├── tasks.md
│       └── decisions.md
└── knowledge/          # things I've learned, organised by topic
    ├── docker.md
    └── react.md

At session start, Claude reads memory/identity.md and knows: who I am, what projects are active, and what I was working on last. No onboarding, no re-explaining context.

Updates to LOS replace managed files cleanly — your memory never gets touched because identity.md is outside the managed scope.

One skill deep-dive: /task-system

Of the six skills, /task-system is the one with the most structure. It runs a BMAD-inspired lifecycle on a single task at a time:

plan → build → verify → fix → learn → close

The plan phase wears three thinking hats in sequence:

Analyst — what are we really solving, what's the domain context
Architect — what's the technical approach, what could break
PM — break it into 8-10 concrete steps, each one atomic

All three hats write into one file — .tasks/active/task-NNN.md. Analysis, architecture notes, plan, work log, verify results, fix attempts, learnings — one file is the truth. No scattered briefs, no Google Docs, no side files.

Two modes:

Gated — human approves each phase. Default.
Loop — Claude auto-advances through phases until STUCK, BLOCKED, or PASS. Use this when you're away.

Status vocabulary is deliberately small: IN_PROGRESS, FAIL, STUCK, BLOCKED, PASS, ABANDONED. STUCK is the only full-stop — two failed fix attempts and the loop exits, waiting for a human.

Real tasks that built this project

This isn't theoretical. Here are the actual tasks from memory/projects/LOS-starter/tasks.md:

Task	Why	Status
Adopt BMAD patterns (task-001)	Onboarding gate, state tracking, enriched skills	Done
Cross-repo sync (task-002)	Both repos need identical task-system structure	Done
Autonomy + handoff guards (task-003)	Loop mode pausing, cross-repo build in wrong repo	Done
Update mechanism (task-004)	No safe way to update old LOS instances	Done
Self-assembling routing (task-005)	Updates wiped custom skill entries from CLAUDE.md	Done

Each of these was a single task file, planned with three hats, built, verified, and closed. The fact that they're all Done is the task system working.

The decisions I had to make

Every decision is logged in decisions.md with a reason. This file answers the question "why is it done this way?" without anyone having to read the code:

Host on GitHub Pages as static HTML

2026-03-28 — Zero-cost, zero-ops, fast to iterate

Single landing page (no framework)

2026-03-28 — Keeps it simple, matches LOS philosophy

Identity in memory/identity.md, not CLAUDE.md

2026-03-29 — Makes CLAUDE.md 100% replaceable on update

LOS:managed markers for update boundary

2026-03-29 — Any file with marker gets replaced, everything else untouched

Self-assembling routing from skill frontmatter

2026-03-29 — No hardcoded skill lists — custom skills auto-route

No CLI for updates — Claude is the update tool

2026-03-29 — /update-los skill fetches from GitHub, simpler than npm tooling

What makes it different

Most dev tooling fights Claude Code. LOS works with it:

Memory is the foundation. memory/identity.md is the source of truth for who I am and what's active. Claude reads it at session start — no re-onboarding, ever.
Identity survives updates. /update-los can replace CLAUDE.md, routing, and skills cleanly because your identity lives outside the managed scope.
Skills are self-assembling. Drop a new skill into .claude/skills/my-thing/SKILL.md, and the routing layer finds it via frontmatter. No config to edit.
LOS:managed markers — every updatable file is tagged so the update mechanism knows exactly what it's allowed to touch.
One file per task. The /task-system skill enforces a single active task file. No scatter, no lost context.

Try it

git clone https://github.com/GadOfir/LOS-starter.git
cd LOS-starter
claude

Then say "start session" and let it bootstrap your first task.

Repo: https://github.com/GadOfir/LOS-starter

Built with: Claude Code + markdown + zero frameworks

DEV Community: Gad Ofir

What I learned building an agent platform that actually ships

Every skill is a first-class citizen

14 integrated services, one audit trail

The CLI is the source of truth

Testing isn't an afterthought

The honest part

A lint that crashes before it asserts is worse than no lint

A lint that crashes before it asserts is worse than no lint

ToolShell's Pillars for Agent Orchestration

1. God, King, Worker — shaped delegation, not a flat pool

2. Contracts as source of truth

3. Plan on the surface, route through contracts

4. Drift detection as a first-class concern

5. Every session ends with a retro

6. Urgent work has its own shape

Policy Cascades for Governed Multi-Tenant Agent Platforms

How the cascade resolves

Narrow-only: the safety property

Mutability classes and hard locks

Skills form a floor, never a ceiling

Multiple companies, complete isolation

Two-layer storage with live effect

What you get

Your LLM Fallback Probably Isn't a Fallback

What happened

Why the fallback didn't help

How we found it

The fix

What we filed as the real defect

Check your own stack — today

Introducing the Agent Platform - 40% Complete (2026-04-28 23:21)

Meet the Agent Platform: A New Way to Work with Claude

Meet the Agent Platform: A New Way to Work with Claude

What's done

What's next

Why this matters

I'm writing this down before I lose the thread

I'm writing this down before I lose the thread

Where do agents actually live?

Human-in-the-workshop, not human-in-the-loop

Why no skills

Tracing is the floor, not the ceiling

RAG first, then lower

Route, trace, RAG

The idea I keep not deleting: hivemind standup

How I automated my own LinkedIn + Dev.to publishing in one afternoon (and what broke along the way)

How I automated my own LinkedIn + Dev.to publishing in one afternoon (and what broke along the way)

Why not just "write a script"?

Dead end 1: Medium

Dev.to: the easy path

Dead end 2: LinkedIn's UGC Posts API

Dead end 3: generating text that looked real but wasn't

The three mistakes I made after that

What the skill does now

How to feed it

What I would do differently

Why this matters

LOS-starter: The Markdown Memory System That Makes Claude Code Remember

LOS-starter: The Markdown Memory System That Makes Claude Code Remember

The Idea

The Stack

What's in the box

The skills that make it work

Memory is the whole point

One skill deep-dive: /task-system

Real tasks that built this project

The decisions I had to make

What makes it different

Try it