Dude is spec-driven development for GitHub Copilot.
Start with a rough idea. Dude turns it into an inspectable specification, an implementation plan, and an ordered task list. It then coordinates the coding, testing, and review work, and requires fresh evidence before a task is marked done.
The whole workflow lives in your repository as Markdown. You can read every decision, correct the intent, and resume work without depending on a hosted service or hidden project state. The core stays small; optional packs add domain specialists, visual systems, release tooling, tracked work, and other capabilities when a project needs them.
Dude requires GitHub Copilot in VS Code or the Copilot CLI. Node.js 20 or later is needed for the bundle's maintenance scripts.
Download the latest dude-bundle-*.zip from
GitHub Releases. Unpack it,
then copy its .github/ and .dude/ directories into the repository you want
to work in:
# from the unpacked release bundle
cp -r .github .dude my-project/Reload VS Code so Copilot picks up the new agents and skills. The core can brainstorm and define any feature. Before implementing software, add the coding pack so Dude has a coder, tester, architect, and code reviewer:
@dude add pack coding
Pack commands fetch from the bundle's configured catalog source. Copy
library/ from this repository only when you want a vendored or offline
catalog. docs/setup.md covers prerequisites and first-run
details.
Start with the idea, in whatever words you have. @dude brainstorm records it in
one file, and every later stage reads from what you wrote:
@dude brainstorm expense entry with receipt upload and manager approval
Dude writes .dude/ideas/001-expense-entry.md, restates the idea under
## Idea, and lists the questions it still needs answered. At first brainstorm,
it assigns a three-digit lifecycle number, one higher than the highest number
already used by this workspace's ideas and packages. That number orders the idea
inventory by capture time and carries over to the feature package. It is not
reserved across branches, so ideas with different slugs can share a number
after a merge. It does not indicate priority, dependency, or execution order.
The Definition Rules cover the identity
checks.
The exact unnumbered slug, expense-entry, remains the command selector. Read
the restatement, correct it if it drifted, and answer what you can in the
**Your answer:** slots. Rough input is fine: first capture fixes obvious
spelling, grammar, and transcription errors and leaves your meaning, tone, and
uncertainty alone. When the notes are already written down, hand over the file
instead:
@dude brainstorm notes/expense-entry.md
Brainstorm stops there and creates no spec package, so nothing is generated from an idea you have not read yet.
Once the idea file reads correctly, one verb carries it the rest of the way:
@dude ship expense-entry
expense-entry is the exact unnumbered slug Dude derived from your idea. It
remains the semantic selector even though the physical idea ledger and package
carry the lifecycle number.
flowchart LR
IDEA["Your idea"]
subgraph SHIP["@dude ship: only the missing stages run"]
direction LR
BRAINSTORM["brainstorm<br/>idea file"] --> DEFINE["define<br/>spec, plan, tasks"] --> WORK["work<br/>implement and verify"]
end
DONE["Feature done"]
IDEA --> BRAINSTORM
WORK --> DONE
@dude ship [<target>] takes exactly one optional target and no flags, and it
runs until done unless an existing Work stop fires. Ship performs no automatic
Git or release action. A missing decision, evidence, or authority still stops
for your input. See the complete Ship policy.
Ship also runs in a repository with nothing on disk. There is no idea file to read then, so the name becomes the whole idea, and Dude has to interview you before it can define anything. Two lines of your own words get you further. Use a bare name to resume a feature that already has an idea or a spec package rather than to start one.
Coding starts after the feature has a durable shape. The idea file preserves
what you meant, including uncertainty. The specification says what must be true.
The plan records how this repository will deliver it, and tasks.md becomes the
execution contract.
That separation keeps product decisions out of implementation guesses. When code exposes a missing decision, Dude routes the gap back to the artifact and owner responsible for it. When work finishes, tests and independent review provide the evidence for closing the task.
After Dude successfully closes one or more targets, the same final response
contains one proportional Completion Closeout:. A bounded task usually needs
only its closed scope and freshly observed worktree and branch state. Feature
and release closeouts can also include evidenced delivery identities and actual
URLs, exact optional cleanup that was not run, and learning already retained or
proposed. Ship closeouts scale the same way. Empty categories are omitted, and a
mixed result covers only the successful closures.
The closeout is read-only, writes no state or report artifact, and works without optional packs. Pack advice already available may supply evidence, but cannot delay reporting or change who has authority.
When the optional rubber-duck pack is installed, Dude runs exactly one
retrospective after final Reviewer approval and before closing a successfully
completed feature. The same rule covers a Ship invocation that completes its
feature. The coordinator writes a dated, append-only entry to
.dude/specs/<NNN>-<slug>/retrospective.md, giving each feature package a
stable place to find its retrospective history.
This retrospective does not run for ordinary or bounded task closes, successful
release runs, or failed, blocked, cancelled, or abandoned endings. Its findings
are advisory and never block or delay close. The universal Completion Closeout:
does not require or link the retrospective file and works unchanged without the
pack.
You can stop after definition and use the package as a plan, or let Dude continue through implementation:
idea -> spec -> plan -> tasks -> code -> verification
The core owns the spec-driven workflow. Packs add capabilities without loading every project with every specialist, instruction, or tool. The catalog lives at library/packs/, and each pack is installed only where it is useful.
| Pack | Adds | Install when |
|---|---|---|
coding |
coder, tester, architect, and code reviewer | you want Dude to implement software |
beads |
a tracked issue board | you need issue-level tracking beyond tasks.md |
web |
backend and frontend specialists | you are building a web application |
a2a |
catalog source for one read-only A2A JavaScript advisor and two source-backed knowledge skills | after disposable Compose and actual-advice validation, you need A2A protocol or JavaScript SDK advice |
clearline |
the Clearline visual system | the project selects Clearline for one or more surfaces |
release |
release engineering and versioning guidance | you publish versioned releases |
rubber-duck |
a read-only retrospective teammate | you want advisory findings at a pending successful feature completion reached through direct feature work or a Ship invocation that completes its feature |
@dude list packs
@dude add pack clearline
@dude remove pack clearline
Packs are ordinary, independent capabilities. Installing one makes it available;
the request or project guidance decides when it applies. Projects can keep local
rules under dude-local-*, including path-scoped choices that use different
visual systems in different parts of one repository.
For a focused catalog query:
node .github/skills/dude-compose/compose.mjs list --use-case ui --json--use-case <id> returns exact matches. JSON pack objects include use_cases;
a pack without a declaration returns []. The source catalog currently holds
19 direct pack entries. The a2a entry now contains its complete planned source
provider set: one read-only JavaScript advisor plus protocol and JavaScript
knowledge skills. Catalog source availability remains separate from installed
host availability. Compose verification covered all 19 catalog packs with 56
warnings, no failures, and no leftovers. In a disposable host, the four
installed A2A files and profile survived build-dev; fresh advisor discovery
and direct guidance reads then produced three observed responses: protocol
guidance, JavaScript guidance, and refusal of an excluded request. Those
disposable installations were removed afterward. A2A is now installed in this
repository's dogfood profile through a separate explicit opt-in to support
Feature 068. A fresh supported Copilot host session discovered and selected the
installed advisor without making a model or advice call. That result does not
prove that an already-running chat hot-reloaded its tool catalog. An existing
chat may require a reload to discover a changed agent catalog. No
other language source was delivered. Feature 068 later added opt-in
agent-to-agent communication to the core extension; it does not need this
pack. Start by asking the model to call dude_a2a_propose with the selected
external config path and profile ID. Review its complete native tool result
before the exact next eligible local approval; an assistant summary or
private-log relay is not a substitute. Source and local distribution have
offline checks, but native result/status visibility and real host use remain
unqualified. Feature 089 adds optional nonblocking collaboration on top of it:
two independent Dudes exchange number advice through
dude_a2a_conversation, each records a bounded local transcript you can watch
live and reread, and A may explicitly use the advice in a first capture.
Ordinary capture is unchanged. One
native run of its normal route
passed on 2026-11-12 on one Windows computer; its strict qualification has
never run natively, so native qualification of that collaboration remains
incomplete. See Agent-to-agent communication.
Installed pack files use the reserved dude-pack-* namespace and survive core
upgrades.
Once the first two stages finish, the feature looks like this on disk:
.dude/ideas/001-expense-entry.md # the idea in your words, plus Dude's questions
.dude/specs/001-expense-entry/
spec.md # what the feature must do
plan.md # how this project will build it
tasks.md # the ordered task list Dude implements from
The split decides which file to edit when something needs to change:
- You own the idea file:
## Idea, your answers to open questions, your assumptions, and anything you defer. Change what the feature means there. - Dude owns the spec package and the workflow metadata:
## Normalized Intent,status: draft|defined|resolved, the exactspec_path:tospec.md, task checkboxes, generated board sections, and the append-only## Coordinator Log.
A resolved idea is terminal and package-less: it records an outcome completed
without ever owning a .dude/specs/** package. Its spec_path: is empty, it
never resolves as a defined owner, and the backlog places a valid resolved idea
in Completed with no task counts. A routine @dude brainstorm refresh leaves
exact status: resolved and an empty spec_path: intact; it never returns the
ledger to draft. Reopening requires an explicit @dude brainstorm <slug>
lifecycle request. Until a reopen request arrives, @dude define and
@dude ship refuse to create a package.
After editing the idea, run @dude define expense-entry to rebuild the package
rather than editing spec.md or plan.md by hand.
For a cross-idea view, open the Canvas or run @dude status, which
prints every idea and feature by lifecycle stage, followed by dependency and
order notes. Both are computed when you read them. Dude no longer updates
.dude/backlog.md or .dude/backlog.html; if your project has copies from an
earlier version, you can delete them.
Ship is a shortcut over three verbs. Run them separately to read the spec before any code exists, or to set your own budgets:
@dude brainstorm expense-entry
@dude define expense-entry
@dude work expense-entry
@dude ship <slug> |
@dude define then @dude work |
|
|---|---|---|
| Stages per command | every stage still missing | one |
| Task budget | unlimited | three by default |
| Pauses between stages | no | yes |
@dude work implements but never defines. Given only an idea file, it finds no
live execution lane, refuses, and points you at @dude define. The manual path
is three verbs, not two. Neither verb adds a lane of its own; both run inside
whichever execution lane is already live.
Ship runs
9AB2
autonomously with an unlimited budget, authorizing the next attempt
itself at recoverable checkpoints. @dude work stays guarded by default and is
the advanced form when you want to set budgets, recovery, or policy yourself.
During an explicit Ship run, the existing pre-Work stage owner applies its eligibility, prerequisite, authority, and safety gates before answerability. A checkpoint label alone does not stop Ship. When the accepted intent and evidence support one clearly dominant conservative disposition, that owner can continue without asking the user. Dude pauses when the choice remains consequential or uncertain. The complete rules are in the Ship command reference.
Brainstorm and define are also the only way to change intent, since Ship never refreshes a package behind your back.
@dude status
@dude status reports the current lane, the live artifact, and the next step.
@dude diff summarizes what Dude changed since your last message, and
@dude self-check verifies that Dude followed its own rules. All three are
read-only.
When implementation runs into a wrong assumption or a missing decision, report it instead of patching the spec by hand:
@dude flag the spec does not say which currencies are allowed
Dude classifies the blocker and routes it to whoever owns that decision.
In a canvas-capable Copilot host, the Dude surface provides Overview, Context, Needs you, New idea, and explicit Review entry. One Open / Closed / All finder covers recorded work. Closed distinguishes completed features from resolved ideas.
Needs you shows current owner-qualified questions and choices. Responses return to the same agent: Sent waits for owner acknowledgment, and Accepted does not mean Applied. The UI neither writes protected workflow state nor executes an operation you consent to.
In New idea, Submit continues the existing brainstorm. Save captures for later without discussion, definition, or execution; Cancel keeps the draft in this tab. Ordinary Defer does not capture an idea or promise persistence. A saved idea requires owner acknowledgment and a reread of the canonical result.
Review lets you annotate an exactly owned canonical HTML mock and send a numbered report with an actual PNG to its waiting agent. Comment text is optional: a numbered pin on a valid target sends its report and image without prose, and comments stay local until you send them. Feedback requests revision; approval stays separate and applies only to the current revision. Capture needs an available Edge, Chrome, or Chromium executable and renders the exact source fresh rather than recording host pixels. Nothing is downloaded automatically; missing capability is shown as unavailable.
Canvas uses the host extension runtime. Consumers need no npm install or browser build. See Canvas responses and Review for capture limits and saved-evidence behavior, or Canvas maintainer acceptance for development checks.
| Command | Purpose |
|---|---|
@dude ship [<target>] |
Run the lifecycle stages a feature still needs, then implement it |
@dude brainstorm <name-or-file.md> |
Create or refresh the idea file, without creating a spec package |
@dude define <slug> |
Build or refresh the spec package from the matching idea |
@dude work [<feature>] |
Implement ready tasks with your own budgets and policy |
@dude status |
Report the current lane, live artifact, and next step |
@dude flag <problem> |
Route a blocker or wrong assumption to its owner |
@dude remember: <fact> |
Record a durable project rule, decision, or constraint |
@dude list packs / @dude add pack <name> |
List or install optional capability packs |
Full grammar, illustrative results, and the maintenance verbs are in docs/commands.md.
One explicit GitHub issue can provide raw material for an ordinary request:
@dude brainstorm E-G-C/dude#20
@dude brainstorm https://github.com/E-G-C/dude/issues/20
@dude ship issue 20
A bare number resolves only in the current repository. To name an issue
elsewhere, use owner/repository#number or a URL; Dude has no
default-repository setting and does not search across repositories.
A reference supplies input only. It does not authorize work. Asking what an issue says gets a direct answer and admits no work; capture or execution asks Dude to classify it. Merely discovering or displaying an issue does not authorize execution.
Some issue execution takes a shorter route than the feature lifecycle:
@dude ship issue <number> fetches, classifies, and executes through the
existing route for the issue. The issue intake decision model
explains when to inspect, ship, define a feature, run bounded work, flag an
active-work blocker, or answer one classification question.
Dude implements straight from tasks.md, which is enough to finish a feature.
Add the beads pack when you want issue-level tracking, richer multi-user
history, or long-running work that deserves a dedicated board:
@dude add pack beads
@dude track
@dude sync Beads to tasks.md
Exactly one place is authoritative at a time. Before @dude track, tasks.md
decides what is ready and done. After it, the tracked board decides and
tasks.md becomes a one-way mirror you can refresh before switching machines.
@dude status reports whether that mirror is current but never syncs it for you.
.
├── .github/ # VS Code/Copilot-discovered Dude engine and configuration
├── .dude/ # project work, memory, state, and bundle metadata
├── library/ # optional pack catalog (install with @dude add pack)
├── docs/ # detailed guides and reference material
└── README.md # this file
The sole bundle manifest is .dude/metadata/bundle-manifest.md. Current source
dogfood and release bundles do not generate a manifest under .github/.
.github/contains only engine/configuration artifacts that VS Code or Copilot discovers: agents, skills, instructions, and workflows where applicable..dude/is the canonical project workspace:ideas/,specs/,memory/,state/, andmetadata/.library/packs/is the catalog of optional packs you install on demand.docs/is the repo-local documentation set for deeper workflow details.
Updating the bundle leaves your product code and active feature work in place.
@dude upgrade --dry-run
@dude upgrade
@dude upgrade --all
Preview first, then reply confirm upgrade to apply exactly that preview;
--all also updates the installed out-of-the-box packs. The changes stay
uncommitted on your current branch for you to review and commit, and a new
session loads them. Git cannot recover uncommitted edits that an update
overwrites in Dude-owned files. Manifest metadata and the namespace convention
for base ownership are described in docs/upgrading.md.
Read these when you need more than the first-feature path:
- Docs index — where to go next.
- Setup and first feature — first-time install, guardrails, and roster customization.
- Commands and prompt shapes — full command reference.
- Workflow modes and lifecycle — what changes when you stop at the plan, use
tasks.md, or move to a tracked board. - Detailed walkthrough — one feature end to end.
- Starting from a PRD draft — use a longer product draft as input.
- Definition and execution reference — advanced details and ownership rules.
- Pack catalog — optional expansions and how to install them.
- Agent-to-agent communication —
dude_a2a_propose, complete native-result review, and local approval for opt-in questions, named verification, and nonblocking two-Dude number advice; real host use remains unqualified. - Upgrading the bundle — update Dude itself safely.
- Repository development workflow — core, pack, project-local, and docs-only changes.