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

imageCI imagePython 3.10+ imageAgent Plugins 1.0 imageLicense: MIT

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

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:

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

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

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

• Docs index
• Quickstart
• Architecture
• Host adapters
• Execution Brief
• Building domain packs
• Evaluation

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