positronic

A personal AI-coding framework — opinionated, solo.

What positronic does — three layers across the lifecycle of a software project:

• Product management — the define skill surfaces assumptions before any code is written; /to-prd, /to-spec, /to-issues lock them down as versioned artifacts. For zero-to-one work, an optional research arc precedes the PRD: /research-market → /ideate → /judge-idea.
• Software engineering — eight behavioral rules (below) and test-driven development (red → green → refactor) where tests verify behavior through public interfaces, not implementation details.
• Agent harness engineering — pick-harness-shape plus a reference corpus of frontier briefs (docs/agentic-patterns/) help pick a custom harness when it's genuinely useful (and an off-the-shelf one otherwise), then lock the load-bearing decisions into a versioned harness/ artifact that /to-spec reads.

The behavioral floor — eight rules Claude follows on every turn:

1. Think Before Coding — state assumptions, ask when uncertain, push back on overcomplication.
2. Read Before You Write — ground every action in actual code; verify APIs and patterns before using them.
3. Minimum Diff — every changed line traces to the request; minimum code for new work, surgical edits for changes.
4. Plain Naming — functions, modules, variables read like plain English; names describe intent.
5. Goal-Driven Execution — define verifiable success; loop until verified, or stop and surface what's blocking.
6. Phase Awareness — name the phase (defining / implementing / diagnosing / shipping) before acting.
7. User-Facing Reliability — show progress on operations >2s; map external failures to one-sentence actionable messages, not raw exceptions.
8. Secret & Data Hygiene — never commit secrets; never log credentials, PII, or auth headers.

AGENTS.md is read by Claude Code and Google Antigravity (since v1.20.3); other tools (Cursor, Codex) are converging on the same convention. The skills/ system is Claude Code only — for cross-tool skill reach, use google-agents-cli. Cloud lean: Google Cloud + Google ADK.

A typical user journey

You arrive with a fuzzy idea — "build X", "fix Y" — and no spec yet.

1. define fires automatically. It interviews you on the problem, surfaces hidden assumptions, frames a falsifiable hypothesis, and routes you to the right pre-PRD path.
2. define picks the route based on what it heard:
   • Zero-to-one with market uncertainty → it prompts /research-market (forum + competitive evidence into research/) → /ideate (ten ranked one-pagers, you pick) → /judge-idea (adversarial gate; verdict is proceed, loop-back, or pivot) → /to-prd.
   • Established space → it prompts /to-prd directly; the research arc is skipped.
3. If a custom LLM harness is on the table, pick-harness-shape fires after /to-prd and before /to-spec. It reads the PRD's constraints, walks the load-bearing decisions (substrate, loop topology, memory, tool layer, gates) — biased toward off-the-shelf when one fits — and writes a versioned harness/ artifact that /to-spec reads. When the tool layer means designing your own MCP server, design-mcp-server walks the server-design decisions (transport, auth, schema discipline, error model, testing) — grounded in docs/agentic-patterns/06_mcp_design_brief.md.
4. /to-spec synthesizes the latest PRD plus the latest harness/ artifact (if present) into a versioned implementation SPEC in specs/.
5. /to-issues breaks the SPEC into independently-grabbable GitHub issues, labeling each afk (Claude can do it solo) or hitl (needs you in the loop).
6. /run-afk-in-loop works through unblocked afk issues in parallel waves. Each issue runs through test-driven-dev, which auto-fires on implementation work. UI work also triggers ui-taste; bugs during implementation auto-fire diagnose.
7. /review-pr before the branch ships — flags must-fix and worth-noting items, including a prompt-file audit when the diff touches prompts or MCP tool descriptions. /audit-drift for projects with versioned PRDs/SPECs/ADRs — sweeps the doc graph for glossary inconsistencies, dead cross-references, ADRs overtaken by the latest SPEC, and orphan ADRs. /audit-failure-modes before a release cut on a maturing system — parallel agents per surface (external deps, concurrency, persistence, resource, config, security, frontend) produce a MECE list of latent failure modes ranked P0/P1/P2.

Skip steps when the phase is already clear: a bug report drops straight into diagnose; a known-good plan can jump to /to-spec; a finished branch can go right to /review-pr.

Skills

Skills are organized by phase (per AGENTS.md §6). Invocation modes: model-invokable = Claude auto-fires the skill when a prompt matches its description; slash-only = user types /skill-name to invoke, zero per-turn context cost.

Skill	Invocation	Phase	What it does
define	model-invokable	defining	Defining-phase orchestrator — surfaces assumptions, frames a falsifiable hypothesis, routes to the right pre-PRD path
pick-harness-shape	model-invokable	defining	Pick the harness shape for an LLM/agent system — custom when genuinely useful, off-the-shelf otherwise; writes a versioned harness/ artifact that /to-spec reads
design-mcp-server	model-invokable	defining	Walk the design decisions for a new MCP server — transport, auth, tool surface, schema discipline, state model, error model, testing
research-market	slash-only	defining	Mine forums + competitive landscape into a versioned research/ artifact
ideate	slash-only	defining	Generate, rank, and pick a product idea grounded in research/
judge-idea	slash-only	defining	Adversarial pass on a winner / PRD / SPEC; verdict is proceed, loop-back, or pivot
to-prd	slash-only	defining	Synthesize the current conversation into a versioned PRD in prds/
to-spec	slash-only	defining	Synthesize the latest PRD + latest harness/ artifact (if present) into a versioned implementation SPEC in specs/
to-issues	slash-only	defining	Break a plan into independently-grabbable GitHub issues; labels each afk or hitl
test-driven-dev	model-invokable	implementing	Test-driven development with red-green-refactor
ui-taste	model-invokable	implementing	Opinionated visual rules; fires on UI work; avoids the generic, cookie-cutter look
run-afk-in-loop	slash-only	implementing	Work through all unblocked AFK issues in parallel waves
diagnose	model-invokable	diagnosing	Disciplined loop for hard bugs and performance regressions
review-pr	slash-only	shipping	Review the current branch before it ships; flags must-fix and worth-noting items
audit-drift	slash-only	shipping	Sweep the project's doc graph (PRDs/SPECs/ADRs/CONTEXT.md) for drift; reports must-fix and worth-noting
audit-failure-modes	slash-only	shipping	Pre-mortem of the system; lists latent failure modes by surface, ranks P0/P1/P2
github-triage	slash-only	meta	Triage GitHub issues through a label-based state machine
deepen-modules	slash-only	meta	Find shallow modules and propose how to deepen them

The system prompt sees AGENTS.md plus descriptions of model-invokable skills only. slash-only skills load on invoke — zero per-turn context cost.

Layout

.
├── AGENTS.md          # behavioral floor (cross-tool, always on)
├── CLAUDE.md          # @AGENTS.md import (Claude Code)
├── .claude-plugin/    # plugin.json registers skills
├── docs/              # reference corpus (frontier briefs on agentic patterns)
└── skills/               # organized by phase (defining / implementing /
    ├── defining/         #   diagnosing / shipping / meta). Each SKILL.md
    ├── implementing/     #   sets `disable-model-invocation: true` for
    ├── diagnosing/       #   slash-only; absence = auto-fires on relevant
    ├── shipping/         #   prompts.
    └── meta/

AFK loop

/to-issues tags each issue afk or hitl. /run-afk-in-loop then works through all unblocked AFK issues in order — picking the next one, implementing it with /test-driven-dev, closing it, and looping until done.

Unattended runs with credit-exhaustion retry:

bash skills/implementing/run-afk-in-loop/scripts/run-afk-loop.sh

Env vars: RETRY_WAIT_SECONDS (default 1800), MAX_ATTEMPTS (default 20).

Adding a skill

Copy an existing skill folder under the right phase (defining/, implementing/, diagnosing/, shipping/, meta/), rename it, edit the SKILL.md frontmatter (disable-model-invocation: true for slash-only; omit for auto-fires), then register the path in .claude-plugin/plugin.json.

MCP servers

MCP servers add Claude Code capabilities. Same lean-context discipline as skills: install only what you use.

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

Add others (Postgres, SQLite, Context7) per-project. User-level MCPs go in ~/.claude.json; project-level in .mcp.json.

Google Cloud and ADK

For Google Cloud or Google ADK projects, install google-agents-cli per-project — multi-tool by construction (Claude Code, Gemini CLI, Codex, Antigravity).

uvx google-agents-cli setup       # full CLI + skills
npx skills add google/agents-cli  # skills only

Skills (all prefixed google-agents-cli-):

Skill	What it does
workflow	Development lifecycle, code preservation, model selection
adk-code	ADK Python API — agents, tools, orchestration, callbacks
scaffold	Project scaffolding (create, enhance, upgrade)
eval	Evaluation — metrics, evalsets, LLM-as-judge, trajectory
deploy	Deployment to Agent Runtime, Cloud Run, GKE, CI/CD
publish	Gemini Enterprise registration
observability	Cloud Trace, logging, third-party integrations

google/adk-samples: sample ADK agents in Python / Java / Go / TypeScript. Reference implementations — clone what you need; don't install as a skill.

Install

Examples use dformoso/positronic; substitute your username if forked.

The two pieces install independently — most users want both.

1. Skills (Claude Code plugin)

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

This also ships the docs/agentic-patterns/ reference corpus — several skills cite it at runtime via ${CLAUDE_SKILL_DIR}-resolved paths, so no separate copy is needed.

2. Behavioral floor (AGENTS.md)

Ask your coding agent to copy AGENTS.md (and CLAUDE.md if Claude Code is your primary tool) from this repo into either:

• ~/.claude/ — applies the floor globally to every project
• a project root — applies it just to that project

Both files are plain text with no dependencies; curl works too.

Acknowledgments

• Andrej Karpathy — observations on LLM coding failure modes (four of the five AGENTS.md principles, packaged into a Claude Code skill by forrestchang).
• Matt Pocock — small composable skills and the SKILL.md format with progressive disclosure.
• Competing Against Luck — Clayton Christensen, Taddy Hall, Karen Dillon, David Duncan. Jobs-to-be-Done methodology. Shapes how define frames the problem and the /research-market → /ideate arc.
• Good Strategy / Bad Strategy — Richard Rumelt. The strategy kernel: diagnosis → guiding policy → coherent action. Mirrored in define's insistence on surfacing assumptions and naming the phase before any code is written.
• Zero to One — Peter Thiel. Zero-to-one product thinking and contrarian truths. Frames the zero-to-one branch in define that triggers the /research-market → /ideate → /judge-idea research arc.
• The Lean Startup — Eric Ries (2011). Build–Measure–Learn and the validated-learning loop. Informs define's falsifiable-hypothesis framing and /judge-idea's proceed / loop-back / pivot verdict.

License

MIT — see LICENSE. Upstream MIT notices preserved.