super-dev

简体中文

A vendor-neutral, evidence-driven engineering harness for coding agents.

super-dev helps an autonomous coding agent move real software work forward without losing control of scope, authority, evidence, or recovery. It is not a code generator, a fixed phase ceremony, or a bundle of infrastructure commands. It is a compact operating protocol for the parts of agentic engineering that remain expensive when code generation becomes cheap:

• keeping the current goal stable;
• preserving the user's work and repository state;
• making high-impact authority explicit;
• defining completion before implementation;
• matching validation to the actual delivery model;
• distinguishing implementation, delivery, runtime behavior, and user acceptance;
• leaving durable, recoverable state.

Status: public release.

Why super-dev

Strong coding agents can inspect repositories, edit multiple files, run tools, debug failures, and deliver changes. The main failure modes move upstream and downstream of code generation:

• solving the wrong version of the problem;
• expanding scope without noticing;
• overwriting unrelated work in a dirty checkout;
• treating a successful command as a successful outcome;
• deploying the wrong branch or stale revision;
• losing decisions and evidence across long sessions;
• mixing private execution state with committed project knowledge.

super-dev turns those failure modes into explicit contracts and gates while preserving agent autonomy for ordinary in-scope work.

Core operating model

request
  -> read the project contract
  -> restate goal, scope, authority, and Done Contract
  -> choose task mode
  -> create the smallest durable spec
  -> isolate implementation
  -> checkpoint before new risk or external mutation
  -> implement and validate
  -> read back authoritative state
  -> close out the spec
  -> sync only reusable, repository-appropriate knowledge
  -> report the proven outcome

The human owns goals, boundaries, high-impact authority, and acceptance. The agent owns exploration, implementation, iteration, and proportionate validation inside that boundary.

Protocol layers

Layer	Responsibility
L0 — Control loop	Restate, current goal, scoped authority, Done Contract, evidence, reverse sync
L1 — Engineering state	Spec, lifecycle todo, project profile, worktree isolation, recovery
L2 — Safety and truth	Mutation gates, privacy boundary, command integrity, evidence freshness
Extensions	Project-owned providers for version control, CI, deployment, logs, data, and runtime verification

The repository contains only L0–L2 and a generic extension contract. Product-specific commands, infrastructure coordinates, credentials, and operational runbooks belong in private project adapters.

Core contracts

Restate first

Before substantial work, state the requested outcome, scope, assumptions, and completion evidence in the agent's own words.

Spec before non-trivial implementation

Use the smallest durable artifact that can preserve the task:

• zero: no spec for a purely mechanical, reversible change;
• fast: compact micro-spec;
• standard: feature spec and visible lifecycle todo;
• deep: feature spec plus explicit alternatives, migration, rollback, or decision records as needed.

Scoped authority

The user's request authorizes ordinary reversible local work needed to fulfill that request. A fresh checkpoint is required before destructive actions, shared-repository mutations, deployments, data changes, credential flows, or material scope expansion.

Worktree-first isolation

For non-trivial Git work, prefer a dedicated worktree and record the base branch, task branch, integration target, delivery target, dirty state, and retention mode. Never reset, clean, stash, or absorb unrelated user work without explicit authorization.

Done by evidence

Validation must prove the Done Contract at the appropriate level:

Level	Evidence
E0	Source inspection, diff, schema, static analysis
E1	Unit tests, lint, type checks, build
E2	Integration, contract, or consumer tests
E3	Deployed or environment-specific runtime checks
E4	User-visible or business acceptance

A build is not a deployment. A deployment is not runtime behavior. A successful response is not automatically the complete user outcome.

Reverse sync and recovery

Close out the task record with the actual change, evidence, deviations, release state, residual risk, and exact next action. Keep the task active when any Done Contract item remains unproven.

Repository structure

super-dev/
├── README.md
├── README.zh-CN.md
├── LICENSE
├── SECURITY.md
├── CONTRIBUTING.md
└── skills/
    └── super-dev/
        ├── SKILL.md
        ├── agents/
        │   └── openai.yaml
        └── references/
            ├── evidence-contract.md
            ├── extension-contract.md
            ├── project-profile.md
            ├── project-sync-boundary.md
            ├── safety-contract.md
            ├── spec-contract.md
            └── worktree-contract.md

There are intentionally no install scripts, executable helpers, runtime samples, or vendor adapters.

Installation

Recommended: Skills CLI

Install from the public GitHub repository:

npx skills add brantshin/super-dev \
  --skill super-dev \
  --global \
  --agent codex \
  --yes

Claude Code:

npx skills add brantshin/super-dev \
  --skill super-dev \
  --global \
  --agent claude-code \
  --yes

Install for both:

npx skills add brantshin/super-dev \
  --skill super-dev \
  --global \
  --agent codex \
  --agent claude-code \
  --yes

Public catalog page

Open super-dev on Agent Skill Hub.

The page includes the published file snapshot, source revision, and a copy-ready install command:

npx skhub add brantshin/super-dev

The skills.sh mirror is available at skills.sh/brantshin/super-dev/super-dev. Its snapshot is generated from anonymous Skills CLI installation telemetry, so the rendered page and search index can lag behind a new publication.

Manual installation

Copy skills/super-dev into the skill directory used by the target agent. For example:

git clone https://github.com/brantshin/super-dev.git
mkdir -p ~/.codex/skills
cp -R super-dev/skills/super-dev ~/.codex/skills/super-dev

Quick start

Invoke the skill explicitly:

Use $super-dev for this task.

First restate the outcome, scope, assumptions, and Done Contract.
Inspect the repository state and choose the task mode.
Proceed autonomously with normal in-scope local work.
Checkpoint before destructive actions, external mutations, or scope expansion.
Validate the final outcome with evidence and leave recoverable state.

For routine use, add a repository instruction such as:

Use super-dev for non-trivial coding, debugging, refactoring, validation, and delivery tasks.
Repository-specific rules and validation requirements take precedence.

Project-specific extensions

super-dev does not prescribe tools. A project can supply private adapters for:

• version control and change review;
• build and CI;
• deployment and release;
• interface, UI, or consumer validation;
• logs and traces;
• databases and configuration;
• messaging and runtime routing.

Each adapter declares read-only and mutating operations, required coordinates, authentication boundaries, checkpoint requirements, normalized evidence, and recovery behavior. See extension-contract.md.

Privacy and publication boundary

The public core must not contain:

• credentials, tokens, cookies, or private configuration;
• personal filesystem paths or private messages;
• internal domains, infrastructure coordinates, or operational runbooks;
• production payloads, traces, logs, screenshots, or database rows;
• private task history, user preferences, handoffs, or memory;
• project-specific deployment and routing instructions.

Use synthetic examples and keep volatile project coordinates in project-owned private documentation.

Design principles

• Autonomy inside scope: avoid approval theater for ordinary local work.
• Hard gates at real risk: checkpoint destructive, external, shared, or irreversible actions.
• Progressive disclosure: keep SKILL.md compact and load references only when needed.
• Evidence over confidence: completion is proven by current, attributable state.
• Repository-native recovery: durable task state survives long sessions and handoffs.
• Vendor neutrality: the protocol defines what must be true, not which product must produce the evidence.
• Explicit non-claims: report partial milestones precisely.

Contributing

Contributions should strengthen a generic engineering contract without embedding organization-specific runtime knowledge. Read CONTRIBUTING.md before proposing changes.

Security

Do not open a public issue for a suspected credential leak or publication-boundary failure. Follow SECURITY.md.

License

MIT. See LICENSE.