Powercode

Controlled, responsible AI usage in software development. "AI accelerates, humans decide."

Powercode is a small, opinionated standard for using AI in software development without giving up control of it. It is a response to "Vibecode" - the speculative, unreviewed use of AI that produces code which looks fine and isn't.

The entire standard rests on one rule:

A human is accountable for everything that ships, and nothing ships unverified.

Everything else in Powercode exists to make that rule enforceable in a real codebase - including one read by coding agents, not just people.

What makes it different

Most "AI policies" restrict AI by task category - "no business logic," "no security-critical code." Those rules get quietly ignored, don't match how people actually work, and a coding agent can only obey them by refusing useful work. Powercode drops the category ban and scales verification by blast radius instead:

Tier	What it covers	Verification
T0 - Contained	Scaffolding, test data, scratch, drafts not yet wired in	Author sanity-check; can't reach production until promoted
T1 - Standard	Feature & business logic, refactors, tooling, shipped docs	Informed human review + automated gates (lint, types, tests)
T2 - High blast radius	Auth, crypto, secrets, data migrations, infra/deploy, anything regulated	Line-by-line domain-owner review + recorded sign-off + ADR if architectural

AI may participate at every tier. What changes is how hard its output is verified before it ships.

Alongside accountability, two further non-negotiables hold at every tier:

Nothing ships unverified - verification depth scales with risk, but never reaches zero.
Confidentiality - secrets, credentials, customer data, and proprietary or regulated source must never be sent to a third-party (cloud) model. The cloud-vs-local inference choice is a governance decision, recorded in an ADR.

What's in this repository

Powercode is a jump-start kit: the principles, the fill-in templates, the agent skills, and a worked example, so you can stand up a Powercode-guided project quickly.

File / directory	Purpose
`docs/Powercode-Manifesto.md`	The principles - project-agnostic philosophy and the tier model. The why.
`POWERCODE.md`	How to adopt Powercode in a project - a project-agnostic implementation guide (the how).
`templates/AGENTS-template.md`	The operative rules, read by humans and coding agents. Copy it into your project and fill in the blanks.
`templates/ADR-template.md`	Architecture Decision Record format, with two worked examples (local-inference and tiered-verification).
`AGENTS.md`	This repo's own rules - the `AGENTS.md` template filled in for a real project, so you can see what a completed one looks like.
`skills/`	Reusable, tool-agnostic agent skills you can drop into a project (see below).
`CONTRIBUTING.md` / `CHANGELOG.md`	How to propose changes to the standard, and the log of changes to it.
`README.md`	This file.

Skills

The skills/ directory holds reusable agent skills that support the Powercode workflow. They are tool-agnostic and copy cleanly into a project's own skills directory:

skills/scout/ - survey an unfamiliar folder and produce a concise, structured report (languages, build files, deps, entry points, tests, CI, git state). Useful for the "look around before you change anything" step.
skills/code-quality-review/ - deliver a blunt, evidence-backed quality verdict by running real tooling (lint, types, tests, coverage, dependency and secret scans), not by guessing. First-class support for Python, C#, and Go. A natural fit for the T1/T2 verification gates.

The manifesto, templates, and skills are deliberately tool-agnostic - no specific AI product is baked in, so the standard outlives any one tool.

Adopting Powercode in your project

Link or copy the manifesto - docs/Powercode-Manifesto.md is the shared why; you usually link to it rather than fork it.
Create your AGENTS.md - copy templates/AGENTS-template.md to AGENTS.md and fill in the [PLACEHOLDERS] and  blocks: your T2 domain owners, your quality-gate commands, and which models are approved for which data.
Write a short implementation doc - describe how your repo enforces the structure: where reviewed code lives versus templates/scratch, and what gates a change must pass. (POWERCODE.md is a project-agnostic guide; DRADIS below is a worked example.)
Record decisions as ADRs - use templates/ADR-template.md, store them in docs/adr/, number them sequentially. The local-vs-cloud inference decision is usually your first one.
Document AI involvement - note it in CHANGELOG.md and commit messages, with the tier and the responsible human:
```
feat: add nextcloud service (drafted with AI, reviewed by @you) [T1]
```

Enforcement is the quality gates, not a disciplinary process: a change that isn't reviewed to its tier, or that fails lint / types / tests / idempotency, does not merge.

Reference implementation

DRADIS - a PyInfra-based homelab fleet manager that implements Powercode end to end: immutable templates in services/, reviewed runnable code in deploys/, idempotent deploys (make dry → make apply), verified downloads, and the tier model mapped onto real directories.
(Add your project here!)

Contributing

Powercode is a living standard - every rule except the non-negotiables can change when a better approach is found. Suggestions, new guardrails, and questions are welcome: open an issue to discuss, or a pull request that justifies the change. Significant changes should come with an ADR.

License

The Powercode documents and templates are released under CC0 1.0 - public domain. Use, adapt, and share them freely, with no conditions. The principles are an invitation, not a licence term: we hope you keep the non-negotiables intact, but you are free to do otherwise.

Inspired by Stefan Laubenberger. More about Powercode.