frame-ship

"Haces las cosas como para Dios, por eso trabajas con excelencia y dedicación."

Node Mise Opencode License Status Public

You ask your coding agent for something. It follows nine steps in a fixed order. It does not write a single line of code until you approve the plan. That is the whole idea.

Español · Glossary

The nine steps

#	Step	What you get
0	Start	nothing — it just explains the rules
1	Agree the goal	`GOAL-<name>.md`
2	Write the requirements	requirements you can test + `DESIGN.md`
3	Propose	`PROPOSAL.md` — still no code
4	Check security / design	a verdict, sometimes a `DECISION-*.md`
5	Build	the code + `TESTS.md`
6	Review	`REVIEW.md` from independent reviewers
7	Verify	`HANDOFF.md`
8	Release	release notes, changelog, git tag

Two more skills, used when they fit: fix-a-bug and open-a-pull-request.

What changes for you

Nothing gets written without your approval. The agent proposes, you decide.

You:    "let people reset their password"

Agent:  step 1 — asks 3 questions, shows you the goal, stops and waits
You:    "yes"
Agent:  step 2 — writes the requirements and the design
Agent:  step 3 — writes PROPOSAL.md and stops
You:    "yes, go ahead"
Agent:  steps 4-8 — builds, reviews, verifies, publishes

Every review is independent. Six separate reviewers look at the same change and none of them sees the others' work. "I found nothing" counts as a result.

Steps are not skippable. If something fails, the agent tries twice in a different way, then asks you. Never a third try.

The agent loads its own instructions. You do not have to remember which step you are on. If the conversation gets too long and gets shortened, it re-reads the rules on its own.

Installation

OpenCode

Add the plugin by name and source in your opencode config (~/.config/opencode/opencode.json for every project, or <your-project>/opencode.json for one):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["frame-ship@github:deuriib/frame-ship"],
}

Or from the command line:

opencode plugin add github:deuriib/frame-ship

Then quit opencode and start it again — config is not reloaded while it runs. Check it worked: the system prompt contains [frame-ship v0.17.1] and the skill tool finds start-here.

You need: opencode, Git + gh signed in (the repo is still private), and Node 22 LTS via mise install.

Working on frame-ship itself? Use a local path instead — see plugins/opencode/INSTALL.md. Never commit a file:/// path to a shared config.

Antigravity CLI (agy)

This repo root is the agy plugin source (agy plugin install .).

agy plugin install https://github.com/deuriib/frame-ship
agy plugin list        # frame-ship shows up

Or per workspace: agy plugin install /path/to/frame-ship from any checkout. Check what loaded with /hooks in the TUI. Turn it off without deleting anything:

agy plugin disable frame-ship
agy plugin enable frame-ship
agy plugin uninstall frame-ship

You need Antigravity CLI v1.2.0+ and Node 22 on your PATH.

Replay a hook without running agy:

node plugins/antigravity/hooks/safety-gate.ts < plugins/antigravity/hooks/fixtures/pretool-allow.json
node plugins/antigravity/hooks/context-inject.ts < plugins/antigravity/hooks/fixtures/preinvocation-first.json

Updating

cd <your-checkout-of-frame-ship>
git pull --ff-only
# quit opencode and start it again

Coming from v0.14.0 or earlier? Every skill, agent, and file was renamed to plain words. There is a one-time cleanup — read MIGRATION.md first. To pin a version:

{
  "plugins": [
    "frame-ship@git+https://github.com/deuriib/frame-ship.git#v0.17.1",
  ],
}

How it works

Nothing here is magic. Three pieces:

Skills — twenty folders in skills/: nine chain skills, plus start-here, four ops skills, and six advisories. Each one tells the agent exactly what to do in that step and when to stop.

Rules — four short files in rules/. These say what is never allowed, no matter which step you are in.

A plugin — a small program that puts the right skill in front of the agent at the right time, so you never have to ask for it.

The plugin has no dependencies and runs as one file.

Project layout

./
├── rules/                  what is always true
│   ├── frame-ship.md       the nine steps, the load order, the hard rules
│   ├── guardrails.md       security, privacy, secrets — the never list
│   ├── skills.md           how skills are chosen
│   ├── subagents.md          how subagents are handed work
│   └── writing.md          how to write in this repo
├── skills/                 nine steps plus gates, ops, advisories
│   ├── start-here/         explains the system
│   ├── agree-the-goal/     → GOAL-<name>.md
│   ├── write-the-requirements/ → testable requirements + DESIGN.md
│   ├── propose/            → PROPOSAL.md, changes nothing
│   ├── check-security/     → threat checklist verdict
│   ├── check-design/       → DECISION-*.md verdict
│   ├── build/              → the code + TESTS.md
│   ├── review/             → REVIEW.md from independent reviewers
│   ├── verify/             → HANDOFF.md
│   ├── release/            → notes, changelog, git tag
│   ├── fix-a-bug/          for a bug or a failing test
│   ├── git-commit/         atomic Conventional Commits
│   ├── github-issues/      tracked issues to branches to PRs
│   └── open-a-pull-request/
├── agents/                 34 helpers: 10 named leads, 9 builders, 15 reviewers
├── plugins/
│   ├── opencode/           the opencode plugin (skills, agents, guardrails)
│   └── antigravity/        the same behaviour as agy hooks
├── docs/
│   ├── GLOSSARY.md         what every word means here
│   └── specs/              requirements, designs, decisions, past work
├── tests/                  the check that runs on every change
├── AGENTS.md               the map of this repo
└── README.md

Commands

npm test              # run the checks
npm run typecheck     # does the plugin compile
npm run version:check # is the version in sync (package.json = plugin.json = README banner = CHANGELOG header)
npm run bump -- patch # bump + fan out per .bump-version.json (preview: --dry-run)

Contributing

Read docs/GLOSSARY.md and rules/writing.md first. They are short.
Start at agree-the-goal for something new, or propose for a small fix.
One problem per change. Never approve your own work.
Run npm test and npm run typecheck before pushing.
After changing a plugin or a skill: quit opencode and start it again.

License

MIT — see LICENSE.