MyFlow
MyFlow is an artifact-led development workflow packaged as a set of agent skills. It carries work through five stages, Scope → Plan → Implement → Verify → Close, and writes a durable artifact at each one, so a fresh session can pick the work up without conversation history.
One skill tree serves every agent. There is no per-agent copy to keep in step.
For the whole workflow on one page — the chain of artifacts, the stage gates, and every skill — see don-smith.github.io/myflow.
Install
Pick the section for your agent, then read First use in a repository.
Every command below is taken from that host's own documentation. Installing into Claude Code, Codex, Cursor, and Pi has been confirmed by a real install; Kilo Code and OpenCode have not. The Claude Code manifests are additionally machine-checked (claude plugin validate .).
Claude Code
/plugin marketplace add don-smith/myflow
/plugin install myflow@myflow
MyFlow keeps your workstream artifacts outside the repository by default, under ~/.myflow. Claude Code will not read or write there unless you say so, so add it once in ~/.claude/settings.json:
{
"permissions": {
"additionalDirectories": ["~/.myflow"]
}
}
Skills then appear as /myflow:scope, /myflow:plan, and so on.
Codex
codex plugin marketplace add don-smith/myflow
Then install MyFlow from /plugins in the Codex CLI, or from the Plugins tab in the ChatGPT desktop app. The repository ships both the portable Agent Plugins manifest (plugin.json) and the marketplace catalog Codex reads (.agents/plugins/marketplace.json). Skills are invoked as $scope, $plan, and so on.
Codex's workspace-write sandbox blocks writes outside the workspace and blocks the network. MyFlow notices, falls back to storing artifacts in the checkout, and says so. That still works, but nothing reaches your artifact remote. To let it use the store directly, allow your MyFlow home and the network in ~/.codex/config.toml:
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
writable_roots = ["/absolute/path/to/your/home/.myflow"]
network_access = true
Without that, nothing is lost: run myflow artifacts import later from a session that can write the store.
Cursor
Cursor reads the portable Agent Plugins manifest (plugin.json) at the repository root, so MyFlow installs as one plugin through a marketplace. Add a marketplace pointing at github.com/don-smith/myflow, then install MyFlow from the plugin list it produces. Skills are invoked as /scope, /plan, and so on.
.cursor-plugin/marketplace.json is Cursor's manifest for a repository that ships several plugins at once. MyFlow is a single plugin, so it does not need one.
To skip the marketplace, copy the skills you want from skills/ into .cursor/skills/ in your project instead.
Pi
pi install git:github.com/don-smith/myflow
Restart Pi afterwards. Pi reads the skills from package.json.
The package declares no Pi extension, so nothing here executes code in your Pi session. Use pi list to inspect installed packages and pi remove <source> to unregister.
Where a skill would rather ask a structured question than a plain-text one, it asks through whatever structured question facility the host provides, and falls back to plain text when there is none. That is host-neutral: MyFlow ships no question UI of its own.
To load a local checkout for one session instead, run pi -e . from the repository root.
Kilo Code and OpenCode
Neither ships its own skill installer. Both read a plain skills/ tree, so the community skills CLI works:
npx skills add don-smith/myflow
That CLI is third party. To avoid it, copy the skill directories by hand instead: into .kilo/skills/ or ~/.kilo/skills/ for Kilo Code, or into ~/.config/opencode/skills/ or the project's .opencode/skills/ for OpenCode. Both also read .agents/skills/, so one copy there serves them together.
Kilo Code invokes a skill by name; OpenCode uses /scope.
First use in a repository
- Start your agent in the target repository.
- Run the
onboard skill. It resolves or creates the repository map, then asks where your workstream artifacts should live.
- Start work with the
scope skill and a rough idea.
- Follow each artifact's recommended next action.
Scope can offer an isolated branch or worktree where repository policy permits, or stay in the current checkout for trunk-based repositories.
Where artifacts live
Workstream artifacts are evidence about your work, not product source, so MyFlow keeps them out of the product repository by default. Where they go is your configuration, held in ~/.myflow/config/myflow.json. There are three shapes:
| Configuration | Artifacts live in | Use it when |
|---|
| Home, no remote | ~/.myflow/repositories/<host>/<owner>/<repo>/workstreams/ | You work on one machine and want artifacts to survive worktree removal. |
| Home, with a private remote | the same directory, pushed to a Git repository you own | You work on more than one machine, or you want a backup. |
| Checkout | <repo>/.myflow/workstreams/, ignored by Git | Your agent is sandboxed away from your home directory, or you want artifacts beside the code. |
onboard asks two questions and then runs the right command for you. To set it up by hand:
myflow artifacts init --location home --remote [email protected]:<you>/myflow-artifacts.git
myflow artifacts init --location home --no-remote
myflow artifacts init --location checkout
The remote is a Git repository you create and own. Keep it private. Artifacts quote code and record decisions. MyFlow warns when it can tell a remote is public, and it names no particular repository anywhere.
Only allowlisted paths are pushed: per-repository workstreams (including stage feedback), repository maps, onboarding records, legacy artifacts, and story/** pages, plus the corpus entry page at repositories/index.html. Story pages quote artifacts into the same private remote. Your configuration, credentials, and raw observations stay on the machine, enforced by both the store's .gitignore and the sync command.
| Command | What it does |
|---|
myflow artifacts status | Reports the store mode, what has not synced, and what still needs importing. |
myflow artifacts sync --workstream <id> | Pushes one workstream. Stages do this for you at every boundary. |
myflow artifacts import | Moves checkout artifacts into the home store, deleting the local copy only after a verified push. |
myflow artifacts pull | Restores remote files missing locally. Never overwrites a local file. |
Run them as myflow artifacts <command> after installing, or node skills/myflow/scripts/cli.mjs artifacts <command> from a checkout. Every command prints one JSON object.
Repository stories
Ask the story skill to tell a repository’s story or answer a question with a dated chapter. It reads the artifact record, writes cited narrative through validated page sources, and assembles offline HTML with three linkable lens tabs. The entry page at repositories/index.html lists narrated repositories; each story links back to it. The skill pulls before writing and syncs the story folder and entry page to the same private artifact remote. Follow skills/story/references/authoring-checklist.md to check evidence, chapter revisions, links, reader behavior and sync before delivery. See skills/story/references/styling.md for reader theme overrides.
Workflow
Onboard repository (when needed)
→ Scope → Plan → Implement → Verify → Close
| Stage | Skill | Output |
|---|
| Onboarding | onboard | Repository map, discovery report, and evaluation record |
| Scope | scope | Alignment artifact, risk and depth decision, selected specialists |
| Plan | plan | Lightweight or full executable plan with a verification map |
| Implement | implement | Green phase commits and an implementation checkpoint |
| Verify | verify | Validation report, linked review evidence, and a manual-verification brief |
| Close | close | Evidence-gated documentation, delivery, learning, and closeout |
After the final green phase, the same parent session loads the installed verify skill and executes it immediately. Invoking verify by hand is recovery/rehydration guidance only, not a command the developer has to remember. Verify loads and executes the sibling code-review skill with the exact implementation scope and accepted plan. Its fresh review lanes cover Correctness and Risk, Standards and Maintainability, and Spec Fidelity. Confirmed P0/P1 findings block; P2 does not block. Close inspects linked passing review evidence and matching provenance instead of trusting only a top-level validation pass.
When work needs correction, record the finding and enter the owning stage. Return as often as needed. The journal records what happened; it never authorizes the move. If a journal write fails, keep the workstream artifact current and retry the write later without inventing history. After any correction or planned slice, run fresh Verify and review before Close. Close reports unresolved audit entries honestly; they do not veto verified work.
design is a collaborative Plan step for material structural decisions; it is not mandatory for lightweight work. research, prototype, domain-modeling, discover, and tdd are selected only when the work needs them.
A fresh session runs node skills/myflow/scripts/resolve-repository-map.mjs discover --cwd <git-root>, reads the map it selects, then reads workstream.md and the authoritative stage artifact. Small work uses the lightweight path; structural work adds Design and a full plan.
Every stage edge (entered, accepted, how it went, completed) is recorded by one command, stage-boundary.mjs, which also syncs. Both the one-question stage pulse and the sync are non-blocking: a declined answer or an unreachable remote is reported and never stops the work.
The normative details live in:
Invoking a skill
MyFlow writes a next action as "the plan skill with <path>", because each agent spells the invocation differently:
| Agent | Invocation |
|---|
| Claude Code | /myflow:<skill> |
| Codex | $<skill> |
| Cursor, OpenCode | /<skill> |
| Pi | /skill:<skill> |
| Kilo Code | name the skill |
Skills only you start
implement and close change the repository and end the workstream, so they are yours to start, not the model's. There is no portable way to say so, because the Agent Skills specification has no such field, so the package ships each host's own mechanism:
| Host | Mechanism | What it gives you |
|---|
| Claude Code | disable-model-invocation: true in the skill's frontmatter | The description never enters the model's context, so the skill cannot be discovered or implicitly invoked. |
| Cursor | the same frontmatter key | The skill is included only when you type /implement or /close. |
| Pi | the same frontmatter key | The skill is hidden from the system prompt; you invoke it by name. |
| Codex | agents/openai.yaml with policy.allow_implicit_invocation: false | Codex will not invoke the skill from a prompt; $implement still works. |
| Kilo Code | none | Their documented frontmatter has no invocation-control field. The skill's description is the only signal. |
| OpenCode | none that ships with the package | Unknown frontmatter fields are ignored. Set it yourself in opencode.json: {"permission": {"skill": {"implement": "ask", "close": "ask"}}}. |
The last two rows are a real limitation, not an oversight. If you run Kilo Code or OpenCode, expect to say no occasionally.
What ships
The core skills, including story, the artifact-store and stage-boundary scripts they call, and the two contract documents. Four manifests describe the same skills/ tree to four ecosystems:
| Manifest | Read by |
|---|
.claude-plugin/plugin.json, .claude-plugin/marketplace.json | Claude Code |
plugin.json (Agent Plugins 1.0.0) | Codex and Cursor, and other clients of the portable format |
.agents/plugins/marketplace.json | Codex, as the catalog codex plugin marketplace add reads |
package.json (pi, bin, files) | Pi, and npm/npx |
MyFlow has no runtime dependencies. Every script under skills/ imports only Node builtins and its own siblings, so a clone installs with any package manager and needs no install step at all.
Development
bun run test # the test suite
npm pack --dry-run # what the package ships
claude plugin validate .
License
MIT
