Get Things Done

Your idea is not a task yet

Turn messy intent into a clear work model, identify the real blocker, execute the next useful action, and require evidence before calling anything done

One canonical GTD core · Agent Skills · Agent Plugins · Host adapters · Execution Briefs · Domain Packs · Evidence-based completion

The problem

Most ideas do not arrive as clean requirements

They arrive half-formed, mixed with assumptions, missing decisions, unclear scope, and several possible next moves

A normal assistant can turn that into a long plan

That is not the same as making the work executable

Get Things Done focuses on the gap between “I have an idea” and “there is a next action we can perform and verify”

It separates what is known from what is assumed, identifies the current blocker, decides whether the work needs clarification, research, decomposition, a decision, validation, execution, or verification, then keeps the state in a reusable Execution Brief

One GTD core, many agent hosts

GTD does not maintain a different reasoning workflow for every AI client

                    Canonical GTD Skills
                           │
          ┌────────────────┼────────────────┐
          │                │                │
      Agent Skills     Agent Plugins    Host Adapters
          │                │                │
          └────────────────┼────────────────┘
                           │
 Claude · ChatGPT · Codex · Cursor · Kimi · Grok · DeepCode · more

The skills/ tree remains the source of truth

Adapters own only discovery paths, manifests, packaging, installation layout, and compatibility checks

That means a host integration cannot quietly fork the GTD decision model or create a second version of the workflow

Supported surfaces

The repository tracks 19 adapter contracts. The label describes the package/export contract GTD verifies, not a claim that every vendor has approved or listed the package in its public marketplace

Target	Support model	Delivery
Agent Skills / compatible agents	Native standard	canonical `skills/` tree
Agent Plugins	Native standard	root `plugin.json`
Claude AI Skills	Portable	Agent Skills package
Claude Code	First-class adapter	Claude plugin + skills
Claude Marketplace	First-class package	`.claude-plugin/marketplace.json`
Claude Cowork	First-class adapter	Claude plugin/skill package
ChatGPT Web	First-class adapter	OpenAI plugin package
ChatGPT Work	First-class adapter	OpenAI plugin package
ChatGPT Plugins	First-class package	`.codex-plugin/plugin.json`
Codex	First-class adapter	OpenAI plugin + Agent Skills fallback
Cursor	First-class adapter	`.cursor/skills`
Kimi Code	First-class adapter	`kimi.plugin.json` + `.kimi-code/skills`
Grok Build	First-class adapter	`.grok/skills`
DeepSeek DeepCode	First-class adapter	`.deepcode/skills`
Homebrew	First-class distribution	HEAD Formula + packaged canonical skills (`Formula/get-things-done.rb`)
Shell Installer	First-class distribution	Multi-host install script (`install.sh`) with named roots and `--target-path`
Vercel skills.sh	First-class distribution metadata	`skills.sh.json`
Contentful Skill Kit	Authoring bridge	typed workflow compilation when needed
Glama	Conditional	enabled only when GTD ships a real `mcp.json`

Glama is intentionally not marked native today because GTD does not currently ship an MCP server

The adapter CLI fails closed instead of manufacturing registry support that does not exist

Public marketplace approval, directory listing, vendor review, and local package conformance are separate states. This repository only claims the states it can verify

See Host adapters and distribution

Companion interoperability

GTD tracks 5 companion tools in adapters/companions.json with strict separation of concerns. Companions participate in the engineering workflow without becoming GTD hosts or runtime dependencies:

Companion	Relationship	Companion role	Boundary
Plugin Autopilot	complementary	agent orchestration	Autopilot schedules agent runs; GTD owns work state, brief, and done contract
Plugin Eval	complementary	plugin and skill evaluation	Eval findings enter GTD as verification evidence; cannot bypass exit gates
Superpowers	complementary	development methodology	Superpowers guides TDD and review disciplines; GTD wraps high-level brief
ArmorCodex	complementary	security review	Security findings enter GTD as blockers/evidence; severity is never rewritten
Context7	optional	documentation retrieval over MCP	Context7 provides external docs context; local code and repo governance win

What GTD does

Messy idea
   ↓
Outcome
   ↓
Facts · Assumptions · Decisions · Unknowns
   ↓
Current blocker
   ↓
Executable work model
   ↓
Definition of Ready
   ↓
Action
   ↓
Review
   ↓
Evidence
   ↓
Done or next action

The core behavior is intentionally domain-independent

Software, marketing, product, and research are added through domain packs that inherit the same decision, readiness, evidence, and handoff rules

Core ideas

Knowledge has types

Type	Meaning
Fact	supported by evidence or an explicit user statement
Assumption	reversible belief accepted so work can continue
Decision	selected option that changes what will be done
Unknown	information that is still unresolved

This prevents an unanswered question from quietly becoming a made-up fact

One active blocker at a time

GTD routes the current blocker to one working mode

clarify · research · decompose · decide · validate · model · execute · verify

After each meaningful cycle, it classifies again

Ready and Done are different gates

Definition of Ready asks whether the next action can be performed safely and meaningfully

Definition of Done asks whether the promised result exists and has supporting evidence

A polished plan can pass neither

Progress must leave evidence

A useful cycle should produce at least one concrete result

a decision settled
an artifact created or changed
an external action executed
verification evidence collected

More analysis alone does not count as execution

Execution Brief

Substantial work is represented as a portable Execution Brief

{
  "version": "1.0",
  "title": "Brand-aware landing page generation",
  "domain": "software",
  "status": "modeling",
  "intent": {
    "problem": "AI-generated landing pages drift toward generic design choices",
    "desired_outcome": "Generated pages consistently follow supplied brand direction",
    "actor": "Design and growth team"
  },
  "scope": {
    "in": ["brand context representation", "generation rules", "review checks"],
    "out": ["full CMS", "analytics platform"],
    "constraints": ["must work across more than one model"]
  },
  "knowledge": {
    "facts": [],
    "assumptions": [],
    "unknowns": []
  },
  "decisions": [],
  "open_decisions": [],
  "workstreams": [],
  "deliverables": [],
  "verification": {
    "success_criteria": [],
    "evidence": []
  },
  "next_action": ""
}

The schema lives at skills/get-things-done/references/execution-brief.schema.json

Built-in domain packs

Domain	Adds
Software	architecture, interfaces, failure modes, testing, deployment checks
Marketing	audience, offer, channel, measurement, experiment and campaign checks
Product	user, job, behavior, scope, trade-off and product outcome checks
Research	question framing, source quality, evidence, uncertainty and reproducibility checks
Advisory	root dilemmas, reversibility, strategic trade-offs, founder alignment, decision frameworks

Need another field such as finance, operations, legal, sales, branding, or media buying

Use the companion building-gtd-domain-packs skill to create a pack without forking the core contract

GTD CLI

python scripts/gtd.py doctor
python scripts/gtd.py list-domains
python scripts/gtd.py new-brief --title "Campaign measurement cleanup" --domain marketing --out brief.json
python scripts/gtd.py validate-brief brief.json --root .
python scripts/gtd.py assess-brief brief.json
python scripts/gtd.py render-brief brief.json --out brief.md
python scripts/gtd.py package --out dist

Adapter CLI

Inspect the compatibility registry and system status:

python scripts/adapters.py status
python scripts/adapters.py list
python scripts/adapters.py capabilities
python scripts/adapters.py query --capability skills
python scripts/adapters.py info cursor
python scripts/adapters.py companions
python scripts/adapters.py interop context7
python scripts/adapters.py validate

Export one host package:

python scripts/adapters.py export cursor --out dist/adapters
python scripts/adapters.py export chatgpt-plugin --out dist/adapters --package
python scripts/adapters.py export homebrew --out dist/adapters
python scripts/adapters.py export shell --out dist/adapters

Export every non-conditional adapter with deterministic ZIP packages and execution report:

python scripts/adapters.py export-all --out dist/adapters --package --report dist/export-report.json

The command exports 18 targets and reports Glama separately until an MCP package exists.

Installation

1. Fastest universal install

Install to the standard Agent Skills user location (~/.agents/skills):

git clone https://github.com/imMamdouhaboammar/get-things-done.git
cd get-things-done
./install.sh --agents

For any custom Agent Skills-compatible directory:

./install.sh --target-path "$HOME/.my-agent/skills"

2. All agents via skills.sh

Install GTD across all detected agent harnesses using the Vercel skills CLI:

npx skills add imMamdouhaboammar/get-things-done --all

Or install globally for specific agents:

npx skills add imMamdouhaboammar/get-things-done -g -a claude-code -a codex -a cursor -y

3. Named host targets via shell installer

./install.sh --target claude
./install.sh --target cursor
./install.sh --target kimi
./install.sh --target grok
./install.sh --target codex
./install.sh --target deepseek

Install to all distinct supported user roots at once:

./install.sh --all --force

4. Homebrew (HEAD)

brew install --HEAD ./Formula/get-things-done.rb
gtd doctor

Distribution manifests and schemas

plugin.json                         Agent Plugins 1.0.0 manifest
.codex-plugin/plugin.json           ChatGPT / Codex plugin manifest
.claude-plugin/plugin.json          Claude plugin manifest
.claude-plugin/marketplace.json     Claude marketplace catalog entry
kimi.plugin.json                    Kimi Code plugin manifest
skills.sh.json                      skills.sh discovery metadata
Formula/get-things-done.rb          Homebrew HEAD Formula
install.sh                          Portable multi-host shell installer
adapters/registry.json              GTD adapter compatibility registry
adapters/registry.schema.json       Adapter registry JSON schema
adapters/companions.json            Companion interoperability registry
adapters/companions.schema.json     Companion registry JSON schema

Verification

CI verifies deterministic repository behavior across Python 3.10, 3.11, 3.12, and 3.13:

Python bytecode compilation (python -m compileall scripts tests)
GTD core tests and CLI wrapper behavior
Execution Brief validation and Ready/Done assessment
Domain pack contracts and collision rules
Skill catalog assets and OpenAI skill metadata
Adapter registry and manifest validation
Companion contract schema conformance and boundary checks
Host export and packaging smoke tests
Deterministic SHA-256 release checksum generation and verification
Installer syntax and bash 3.2 compatibility
Homebrew formula syntax validation

Behavioral model evals remain separate from deterministic tests.

Repository map

plugin.json
.codex-plugin/
.claude-plugin/
kimi.plugin.json
skills.sh.json
Formula/
  get-things-done.rb
install.sh
adapters/
  registry.json
  registry.schema.json
  companions.json
  companions.schema.json
skills/
  get-things-done/
  building-gtd-domain-packs/
  consult-dad/
scripts/
  gtd.py
  adapters.py
  package_skills.py
  release_checksums.py
  catalog_stylist.py
docs/
evals/
examples/
tests/

Docs

Design principle

Never confuse thinking with progress

A useful agent should make uncertainty visible, move the smallest consequential thing forward, and prove what changed

License

MIT

Maintained by Mamdouh Aboammar

Navigation Menu

Repository files navigation

Get Things Done

Your idea is not a task yet

The problem

One GTD core, many agent hosts

Supported surfaces

Companion interoperability

What GTD does

Core ideas

Knowledge has types

One active blocker at a time

Ready and Done are different gates

Progress must leave evidence

Execution Brief

Built-in domain packs

GTD CLI

Adapter CLI

Installation

1. Fastest universal install

2. All agents via skills.sh

3. Named host targets via shell installer

4. Homebrew (HEAD)

Distribution manifests and schemas

Verification

Repository map

Docs

Design principle

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
Formula		Formula
adapters		adapters
docs		docs
evals		evals
examples		examples
scripts		scripts
skills		skills
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
kimi.plugin.json		kimi.plugin.json
plugin.json		plugin.json
pyproject.toml		pyproject.toml
skills.sh.json		skills.sh.json

Latest commit

History

Folders and files

Repository files navigation

Get Things Done

Your idea is not a task yet

The problem

One GTD core, many agent hosts

Supported surfaces

Companion interoperability

What GTD does

Core ideas

Knowledge has types

One active blocker at a time

Ready and Done are different gates

Progress must leave evidence

Execution Brief

Built-in domain packs

GTD CLI

Adapter CLI

Installation

1. Fastest universal install

2. All agents via skills.sh

3. Named host targets via shell installer

4. Homebrew (HEAD)

Distribution manifests and schemas

Verification

Repository map

Docs

Design principle

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages