positronic

Positronic is a personal framework for planning, building, and checking software with coding agents. It keeps agreed product and engineering decisions in Markdown: a product requirements document (PRD), journeys, specifications, tasks, and short change records.

Start with the smallest route that fits the request. The catalog holds specialized guidance.

AGENTS.md holds the behavioral floor: inspect before changing, keep changes small, use clear language, prove the result, choose the route that fits, protect data, and integrate independent work. It is read by clients that support project instructions.

The skills/ system follows the open Agent Skills folder layout. Register skills/ with the client instead of assuming a checkout link is discoverable. See Install for client-specific commands.

Start with the smallest route

Need	Start here
Fix a bug or make a small known change	diagnose or test-driven-dev
Turn a settled plan into code	to-spec, then to-issues
Work an existing backlog	run-wave for supervised batches; work-queue for a persistent controller
Define a new product or changed product promise	define
Choose or change deployment, a provider, or a one-way cutover	to-infrastructure, then go-live
Simplify an accreted system	clean-house, then improve-readability where needed

The route table is the normal entry point. Change tier decides how much definition work a request needs; a small fix does not create product artifacts.

Full lifecycle, when it helps

For a new or changed product, the usual chain is define, PRD, journeys, optional mockups, harness, or infrastructure, then SPEC and tasks. Implement through supervised run-wave batches or the persistent work-queue controller. Review before shipping; use go-live for first traffic or an irreversible cutover, then readout after the measurement window.

Definition bodies state the latest approved target. Direct Change records explain accepted changes, while tasks and their checks show what is complete. The change-tier and cascade guide decides which downstream work is affected.

Skills

Use the skill catalog to find the route, inputs, and outputs. Explicit skills use $name in Codex, /skills:name in the Claude plugin, or /name for a native/local Claude skill. A client without commands can request the skill by name.

MCP servers

MCP servers add capabilities to any of the four tools. Same lean-context discipline as skills: install only what you use.

Server	Use	Install (Claude Code)
Playwright	Browser automation, UI verification	claude mcp add playwright npx '@playwright/mcp@latest'
GitHub	Issues, PRs, repo search	See the official install guide

Add other servers only for a concrete project need. Use each client's documented project or user MCP configuration; Antigravity also has an MCP settings UI, and Gemini CLI supplies an MCP command.

Install

Examples use dformoso/positronic; substitute your fork when needed. Keep the skills/ directory beside its shared docs/ files: individual copied SKILL.md files lose their references.

Claude Code

/plugin marketplace add dformoso/positronic
/plugin install skills@positronic

Plugin commands use the skills namespace: /skills:to-spec, for example. For a native or local Claude skill, use /to-spec. Put AGENTS.md and CLAUDE.md in the project root or your configured global instructions directory.

Codex

codex plugin marketplace add dformoso/positronic
codex plugin add positronic@positronic

Explicit-only native or local Codex skills use $name, such as $to-spec. Keep AGENTS.md at the project root or in Codex's configured global instructions location.

Antigravity and Gemini CLI

Register the checkout's skills/ directory through the platform's documented project or global skill mechanism. Do not assume a Unix symlink or home-directory layout. Copy only the workflow stubs you use from .agents/workflows/; each stub resolves the skill through the active index.

For Gemini CLI, configure AGENTS.md as a context file when needed:

{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Notes

• The in-repo .agents/skills link is optional. If a checkout materializes it as a text file, register skills/ with the client instead.
• No GEMINI.md ships on purpose: Antigravity gives it precedence over AGENTS.md.

Acknowledgments

• Andrej Karpathy — observations on LLM coding failure modes that seeded the AGENTS.md floor, packaged into a skill by forrestchang.
• Matt Pocock — the small composable SKILL.md format with progressive disclosure.
• Jobs-to-be-Done (Competing Against Luck), the strategy kernel (Good Strategy / Bad Strategy), zero-to-one thinking (Zero to One), and Build–Measure–Learn (The Lean Startup) — shape how define and the /research-market → /ideate arc frame the problem.

License

MIT — see LICENSE. Upstream MIT notices preserved.