Product overview

Source: docs/product/overview.mdVerified 2026-10-15

The problem

An AI coding agent starts every session from zero. Decisions made last week, the reason one library was rejected, the bug that took an afternoon: none of it survives the session unless someone writes it down where the next session will look. At the same time, the agent's defaults are not the habits of a careful engineer: it commits without running the right checks, claims "fixed" without evidence, reviews its own code, installs dependencies unasked and forgets the user's language after compaction.

What developer-os is

A Claude Code plugin, installed from this repository as a plugin marketplace, that adds two things:

1. Long-term memory in an Obsidian vault. Six brain-* skills let the agent search the vault before a task, capture decisions and lessons into the vault's _inbox/ while it works, and help the user review, garden and consolidate what was captured. The vault is plain Markdown; the agent reads and writes it with its own file tools. The user approves everything that becomes knowledge.
2. An engineering operating model. Core rules loaded into every session, workflow skills (review, spec, audit, backlog, PR cycle, triage, deploy checklist, docs sync, session wrap-up), conventions skills, five specialist agents, four output styles and a small Bash guard.

The plugin is Markdown and JSON plus three Python 3 hook scripts (standard library only). There is no server, database, index, binary, background job or network call in the plugin itself.

Who it is for

• The primary user is a developer working alone or in a small team on several client and product repositories with Claude Code, who wants decisions to outlive sessions and repositories.
• A secondary user runs Codex: scripts/install-codex.sh copies the skills and the core rules into Codex's locations. This path is best-effort and untested on releases (README, Codex).

Product principles

1. The human approves what becomes knowledge. The agent creates notes only in _inbox/ with status: inbox; it edits, moves or archives any other note only after the user names it.
2. Archive, never delete. Retired, merged and rejected notes move to _archive/ with status: archived.
3. Propose, then act on a named yes. Every skill that changes files, git state or anything outside the machine stops at a defined point and asks; silence or "looks good" is not approval. Each action skill states its ## Stop point and ## Never sections, and scripts/check.sh fails without them.
4. Evidence over declaration. Findings carry a file and line, reviews rate on one P0–P3 scale, blocking findings go to a fresh verifier, and "works" needs test output.
5. One fact in one place. Code facts and plans stay in the repository; lessons that outlive a repository go to the vault; user preferences go to auto-memory or ~/.claude/CLAUDE.md (workflow.md, Where knowledge belongs).
6. Small fixed cost per session. The core rules are capped at 8192 bytes and the skill descriptions at 12000 characters in total, because both load into every session.
7. No runtime. Anything that would need a process, a schedule or the network is either left to Claude Code itself (routines, the marketplace) or not built.

Scope

In scope for the first release:

The README lists every component by name (What's inside); the functional specification gives each one's contract.

Out of scope, on purpose:

• A CLI, installer, updater, daemon, index or search engine. The earlier CLI was removed on 2026-10-14 (decisions D1).
• Any automatic write to the vault outside _inbox/, and any automatic promotion of a note.
• Sending anything: no email, chat, issue or PR comment is posted by a skill on its own. client-reply drafts; session-retro prints a gh issue create command for the user to run.
• A Codex manifest, Codex hooks, agents or output styles.
• Running evals in CI.

How it is distributed

• Install: /plugin marketplace add msolecki/developer-os, then /plugin install developer-os@developer-os. The marketplace (.claude-plugin/marketplace.json) points at ./plugin.
• The marketplace serves the repository's default branch, main, which moves only on a release.
• License: MIT. No paid tier, no telemetry.

Status

Release 0.2.4; installs follow main, which moves only on a release. See CHANGELOG.md for what each release changed.

Primary risks