aidd-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
aidd/__init__.py ADDED
@@ -0,0 +1,10 @@
1
+ """AIDD — a methodology for working with AI coding agents.
2
+
3
+ This package is the CLI distribution channel: `pip install -e .` from the
4
+ repo root gives you the `aidd` command. It's a thin dispatcher over the
5
+ stdlib-only scripts in skill/scripts/ — no logic lives twice. The Claude
6
+ Code skill itself (SKILL.md + hooks) is a separate distribution channel
7
+ (see ../skill/) for when an AI agent, not a human at a terminal, is driving.
8
+ """
9
+
10
+ __version__ = "0.1.0"
aidd/cli.py ADDED
@@ -0,0 +1,359 @@
1
+ """aidd — command-line entry point.
2
+
3
+ A thin dispatcher, not a reimplementation: every subcommand shells out to the
4
+ matching stdlib-only script under skill/scripts/, the same scripts the
5
+ Claude Code skill's hooks call. One implementation, two distribution
6
+ channels (this CLI for a human at a terminal or CI; the skill's hooks for an
7
+ AI agent) — never two copies of the logic to keep in sync.
8
+ """
9
+ import argparse
10
+ import subprocess
11
+ import sys
12
+ from pathlib import Path
13
+
14
+
15
+ def _find_scripts_dir() -> Path:
16
+ """Locate skill/scripts/ relative to this file. Works for an editable
17
+ install (`pip install -e .`, source layout preserved) and for running
18
+ straight from a repo checkout. A non-editable wheel install would need
19
+ skill/ bundled as package data at the same relative position — until
20
+ this is published that way, this lookup is the one source of truth."""
21
+ here = Path(__file__).resolve()
22
+ candidate = here.parent.parent / "skill" / "scripts"
23
+ if candidate.is_dir():
24
+ return candidate
25
+ raise SystemExit(
26
+ "Could not locate skill/scripts/ relative to the installed aidd package "
27
+ f"(looked at {candidate}). If you're running from a wheel install rather "
28
+ "than a repo checkout or `pip install -e .`, this lookup doesn't support "
29
+ "that yet — see aidd/cli.py's _find_scripts_dir()."
30
+ )
31
+
32
+
33
+ def _run(script_name: str, args: list, cwd: Path = None) -> int:
34
+ scripts_dir = _find_scripts_dir()
35
+ result = subprocess.run(
36
+ [sys.executable, str(scripts_dir / script_name), *args],
37
+ cwd=str(cwd) if cwd else None,
38
+ )
39
+ return result.returncode
40
+
41
+
42
+ def cmd_search(args):
43
+ return _run("find_spec.py", args.query)
44
+
45
+
46
+ def cmd_tree(args):
47
+ return _run("find_spec.py", ["--tree", args.spec_id])
48
+
49
+
50
+ def cmd_list(args):
51
+ return _run("find_spec.py", ["--list"])
52
+
53
+
54
+ def cmd_reindex(args):
55
+ return _run("find_spec.py", ["--reindex"])
56
+
57
+
58
+ def cmd_check(args):
59
+ return _run("check_spec.py", [args.spec_dir])
60
+
61
+
62
+ def cmd_check_charter(args):
63
+ return _run("check_charter.py", [args.root] if args.root else [])
64
+
65
+
66
+ def cmd_tasks_to_issues(args):
67
+ # Every provider-specific flag (--provider, --repo, --org, --project,
68
+ # --work-item-type, --workspace, --repo-slug) is forwarded verbatim via
69
+ # `provider_args` (argparse.REMAINDER below) instead of re-declared here
70
+ # one by one — tasks_to_issues.py's own argparse is the single source of
71
+ # truth for what a provider accepts; this CLI never re-lists it and so
72
+ # can't drift out of sync with it the way the old --repo-only version did.
73
+ return _run("tasks_to_issues.py", [args.tasks_md, *args.provider_args])
74
+
75
+
76
+ def cmd_marketplace_list(args):
77
+ return _run("marketplace.py", ["list"])
78
+
79
+
80
+ def cmd_marketplace_search(args):
81
+ return _run("marketplace.py", ["search", args.query])
82
+
83
+
84
+ def cmd_marketplace_install(args):
85
+ mp_args = ["install", args.package_id, args.project_root]
86
+ if args.force:
87
+ mp_args.append("--force")
88
+ return _run("marketplace.py", mp_args)
89
+
90
+
91
+ def cmd_marketplace_remove(args):
92
+ mp_args = ["remove", args.package_id, args.project_root]
93
+ if args.force:
94
+ mp_args.append("--force")
95
+ return _run("marketplace.py", mp_args)
96
+
97
+
98
+ def cmd_adapters_list(args):
99
+ return _run("generate_adapters.py", ["--list"])
100
+
101
+
102
+ def cmd_adapters_generate(args):
103
+ generate_args = [args.target, args.project_root]
104
+ if args.force:
105
+ generate_args.append("--force")
106
+ return _run("generate_adapters.py", generate_args)
107
+
108
+
109
+ def cmd_extensions_list(args):
110
+ return _run("extension_registry.py", ["list"])
111
+
112
+
113
+ def cmd_extensions_info(args):
114
+ return _run("extension_registry.py", ["info", args.id])
115
+
116
+
117
+ def cmd_extensions_enable(args):
118
+ return _run("extension_registry.py", ["enable", args.id])
119
+
120
+
121
+ def cmd_extensions_disable(args):
122
+ return _run("extension_registry.py", ["disable", args.id])
123
+
124
+
125
+ def cmd_tracker_sync(args):
126
+ # Same forwarding discipline as cmd_tasks_to_issues: only the positional
127
+ # tasks_md is declared here, every provider-specific flag (--provider,
128
+ # --repo, --org, --project, --work-item-type, --workspace, --repo-slug,
129
+ # --apply) is forwarded verbatim via provider_args (argparse.REMAINDER).
130
+ return _run("sync_issues.py", [args.tasks_md, *args.provider_args])
131
+
132
+
133
+ def cmd_tracker_link_pr(args):
134
+ # tasks_md is a positional here (unlike link_pr_to_task.py's own
135
+ # --tasks-md flag) so it anchors argparse.REMAINDER the same way
136
+ # cmd_tasks_to_issues/cmd_tracker_sync's leading positional does.
137
+ # argparse.REMAINDER only swallows a trailing run of flag-looking
138
+ # tokens (--pr-url, --branch, --task-id, --provider, --apply, ...)
139
+ # when a bare positional value precedes them; a REMAINDER-only
140
+ # subparser with --tasks-md declared as its own leading flag breaks
141
+ # (the first "--task-id"-shaped token after --tasks-md's value gets
142
+ # eaten as an unrecognized optional instead of forwarded — verified
143
+ # empirically). Translating back to --tasks-md here keeps
144
+ # link_pr_to_task.py's own CLI untouched.
145
+ return _run("link_pr_to_task.py", ["--tasks-md", args.tasks_md, *args.link_args])
146
+
147
+
148
+ def cmd_ci_install(args):
149
+ ci_args = [args.target, args.project_root]
150
+ if args.force:
151
+ ci_args.append("--force")
152
+ return _run("install_ci.py", ci_args)
153
+
154
+
155
+ def cmd_init(args):
156
+ """Copy the tool-agnostic .aidd/ bundle (methodology + templates +
157
+ scripts, no Claude-specific pieces) into a target project. This is
158
+ exactly what adapters/README.md's manual `cp -r dot-aidd <project>/.aidd`
159
+ step does — automated, so it's one command instead of a copy-paste."""
160
+ import shutil
161
+
162
+ repo_root = Path(__file__).resolve().parent.parent
163
+ source = repo_root / "adapters" / "dot-aidd"
164
+ if not source.is_dir():
165
+ print(f"Could not find the .aidd bundle to install (looked at {source}).", file=sys.stderr)
166
+ return 2
167
+
168
+ target = Path(args.target).resolve() / ".aidd"
169
+ if target.exists() and not args.force:
170
+ print(f"{target} already exists — pass --force to overwrite, or remove it first.", file=sys.stderr)
171
+ return 1
172
+
173
+ if target.exists():
174
+ shutil.rmtree(target)
175
+ shutil.copytree(source, target, ignore=shutil.ignore_patterns("__pycache__"))
176
+ print(f"Installed AIDD's methodology + scripts to {target}")
177
+ print("Next: add AGENTS.md's AIDD section (see adapters/AGENTS.md.snippet) so your")
178
+ print("agent tool actually reads it — `aidd init` alone doesn't wire that up.")
179
+ print("For Gemini CLI, Cursor, Windsurf, Cline, or GitHub Copilot, also run:")
180
+ print(f" aidd adapters generate all {args.target}")
181
+ return 0
182
+
183
+
184
+ def build_parser():
185
+ parser = argparse.ArgumentParser(
186
+ prog="aidd",
187
+ description="AIDD — a methodology for working with AI coding agents.",
188
+ )
189
+ sub = parser.add_subparsers(dest="command", required=True)
190
+
191
+ p_init = sub.add_parser("init", help="Install the .aidd/ bundle into a project")
192
+ p_init.add_argument("target", nargs="?", default=".", help="Target project directory (default: cwd)")
193
+ p_init.add_argument("--force", action="store_true", help="Overwrite an existing .aidd/")
194
+ p_init.set_defaults(func=cmd_init)
195
+
196
+ p_search = sub.add_parser("search", help="Search the spec graph before creating something new")
197
+ p_search.add_argument("query", nargs="+", help="Keywords or a SCREEN-XX/CTL-nnn/COMP-nnn/API-nnn code")
198
+ p_search.set_defaults(func=cmd_search)
199
+
200
+ p_tree = sub.add_parser("tree", help="Print one spec's use-case -> screen -> component -> control -> API graph")
201
+ p_tree.add_argument("spec_id")
202
+ p_tree.set_defaults(func=cmd_tree)
203
+
204
+ p_list = sub.add_parser("list", help="List every spec from the index")
205
+ p_list.set_defaults(func=cmd_list)
206
+
207
+ p_reindex = sub.add_parser("reindex", help="Force a full rebuild of specs/index.toon")
208
+ p_reindex.set_defaults(func=cmd_reindex)
209
+
210
+ p_check = sub.add_parser("check", help="Run the mechanical gap-checker on one spec folder")
211
+ p_check.add_argument("spec_dir")
212
+ p_check.set_defaults(func=cmd_check)
213
+
214
+ p_cc = sub.add_parser("check-charter", help="Run charter.md's checkable rules")
215
+ p_cc.add_argument("root", nargs="?", default=None, help="Project root (default: cwd)")
216
+ p_cc.set_defaults(func=cmd_check_charter)
217
+
218
+ p_t2i = sub.add_parser(
219
+ "tasks-to-issues",
220
+ help="Turn an approved tasks.md into real issues (GitHub, Azure DevOps, or Bitbucket)",
221
+ description="Provider-specific flags (--provider, --repo, --org, --project, "
222
+ "--work-item-type, --workspace, --repo-slug, --apply) are forwarded as-is — "
223
+ "run 'python skill/scripts/tasks_to_issues.py --help' for the full list.",
224
+ )
225
+ p_t2i.add_argument("tasks_md")
226
+ p_t2i.add_argument("provider_args", nargs=argparse.REMAINDER,
227
+ help="Forwarded verbatim to tasks_to_issues.py, e.g. --provider azure_devops --org ... --apply")
228
+ p_t2i.set_defaults(func=cmd_tasks_to_issues)
229
+
230
+ p_adapters = sub.add_parser(
231
+ "adapters",
232
+ help="Generate native command files for other agent tools (Gemini CLI, Cursor, Windsurf, Cline, Copilot)",
233
+ description="Renders commands/aidd-*.md into each agent tool's own native command "
234
+ "format and directory. Claude Code, OpenCode, and Codex are not covered here — "
235
+ "see adapters/README.md, they already have a richer native mechanism.",
236
+ )
237
+ adapters_sub = p_adapters.add_subparsers(dest="adapters_command", required=True)
238
+
239
+ p_adapters_list = adapters_sub.add_parser("list", help="List available adapter targets")
240
+ p_adapters_list.set_defaults(func=cmd_adapters_list)
241
+
242
+ p_adapters_generate = adapters_sub.add_parser(
243
+ "generate", help="Write native command files for one target (or 'all') into a project"
244
+ )
245
+ p_adapters_generate.add_argument("target", help="gemini | cursor | windsurf | cline | copilot | all")
246
+ p_adapters_generate.add_argument("project_root", nargs="?", default=".", help="Target project directory (default: cwd)")
247
+ p_adapters_generate.add_argument("--force", action="store_true", help="Overwrite files that already exist")
248
+ p_adapters_generate.set_defaults(func=cmd_adapters_generate)
249
+
250
+ p_marketplace = sub.add_parser(
251
+ "marketplace",
252
+ help="Browse and install third-party packages from catalog/ (providers/adapters/templates/hooks)",
253
+ description="See catalog/README.md for what a package is and how to submit one. All 4 "
254
+ "kinds (adapter/template/provider/hook) can be listed, searched, and installed — "
255
+ "an installed provider/hook is auto-discovered from .aidd/extensions/, see "
256
+ "skill/scripts/extension_registry.py.",
257
+ )
258
+ marketplace_sub = p_marketplace.add_subparsers(dest="marketplace_command", required=True)
259
+
260
+ p_mp_list = marketplace_sub.add_parser("list", help="List every package in the catalog")
261
+ p_mp_list.set_defaults(func=cmd_marketplace_list)
262
+
263
+ p_mp_search = marketplace_sub.add_parser("search", help="Search the catalog by id/name/description")
264
+ p_mp_search.add_argument("query")
265
+ p_mp_search.set_defaults(func=cmd_marketplace_search)
266
+
267
+ p_mp_install = marketplace_sub.add_parser("install", help="Install a package into a project")
268
+ p_mp_install.add_argument("package_id")
269
+ p_mp_install.add_argument("project_root", nargs="?", default=".")
270
+ p_mp_install.add_argument("--force", action="store_true", help="Override a file-conflict refusal")
271
+ p_mp_install.set_defaults(func=cmd_marketplace_install)
272
+
273
+ p_mp_remove = marketplace_sub.add_parser("remove", help="Remove an installed package from a project")
274
+ p_mp_remove.add_argument("package_id")
275
+ p_mp_remove.add_argument("project_root", nargs="?", default=".")
276
+ p_mp_remove.add_argument("--force", action="store_true", help="Remove even files modified since install")
277
+ p_mp_remove.set_defaults(func=cmd_marketplace_remove)
278
+
279
+ p_extensions = sub.add_parser(
280
+ "extensions",
281
+ help="List, inspect, enable, or disable auto-discovered provider/adapter/hook extensions",
282
+ description="Extensions are discovered from skill/extensions/**/manifest.json (first-party) "
283
+ "and <project>/.aidd/extensions/**/manifest.json (project-local, including anything "
284
+ "'aidd marketplace install' put there) — see skill/scripts/extension_registry.py.",
285
+ )
286
+ extensions_sub = p_extensions.add_subparsers(dest="extensions_command", required=True)
287
+
288
+ p_ext_list = extensions_sub.add_parser("list", help="List every discovered extension")
289
+ p_ext_list.set_defaults(func=cmd_extensions_list)
290
+
291
+ p_ext_info = extensions_sub.add_parser("info", help="Show one extension's manifest")
292
+ p_ext_info.add_argument("id")
293
+ p_ext_info.set_defaults(func=cmd_extensions_info)
294
+
295
+ p_ext_enable = extensions_sub.add_parser("enable", help="Enable an extension")
296
+ p_ext_enable.add_argument("id")
297
+ p_ext_enable.set_defaults(func=cmd_extensions_enable)
298
+
299
+ p_ext_disable = extensions_sub.add_parser("disable", help="Disable an extension")
300
+ p_ext_disable.add_argument("id")
301
+ p_ext_disable.set_defaults(func=cmd_extensions_disable)
302
+
303
+ p_tracker = sub.add_parser(
304
+ "tracker",
305
+ help="Sync tasks.md status from the tracker and link opened PRs to their task's issue",
306
+ description="See skill/scripts/sync_issues.py and skill/scripts/link_pr_to_task.py.",
307
+ )
308
+ tracker_sub = p_tracker.add_subparsers(dest="tracker_command", required=True)
309
+
310
+ p_tracker_sync = tracker_sub.add_parser(
311
+ "sync",
312
+ help="Diff (or write, with --apply) tasks.md's Status column against live tracker status",
313
+ description="Provider-specific flags (--provider, --repo, --org, --project, "
314
+ "--work-item-type, --workspace, --repo-slug, --apply) are forwarded as-is — "
315
+ "run 'python skill/scripts/sync_issues.py --help' for the full list.",
316
+ )
317
+ p_tracker_sync.add_argument("tasks_md")
318
+ p_tracker_sync.add_argument("provider_args", nargs=argparse.REMAINDER,
319
+ help="Forwarded verbatim to sync_issues.py, e.g. --provider azure_devops --org ... --apply")
320
+ p_tracker_sync.set_defaults(func=cmd_tracker_sync)
321
+
322
+ p_tracker_link = tracker_sub.add_parser(
323
+ "link-pr",
324
+ help="Attach an opened PR's URL to its task's tracker issue and tasks.md row",
325
+ description="tasks_md is positional here (translated back to link_pr_to_task.py's own "
326
+ "--tasks-md flag). Every other flag (--pr-url, --branch, --task-id, --provider, "
327
+ "--apply, and provider-specific flags) is forwarded as-is — run "
328
+ "'python skill/scripts/link_pr_to_task.py --help' for the full list.",
329
+ )
330
+ p_tracker_link.add_argument("tasks_md", help="Path to a spec's tasks.md")
331
+ p_tracker_link.add_argument("link_args", nargs=argparse.REMAINDER,
332
+ help="Forwarded verbatim to link_pr_to_task.py, e.g. --pr-url ... --branch ... --apply")
333
+ p_tracker_link.set_defaults(func=cmd_tracker_link_pr)
334
+
335
+ p_ci = sub.add_parser(
336
+ "ci",
337
+ help="Install a CI workflow file (GitHub Actions or Azure Pipelines) for this project",
338
+ description="See skill/scripts/install_ci.py and skill/templates/ci/*.yml. Opt-in and "
339
+ "explicit, on purpose — nothing else in AIDD writes this file for you.",
340
+ )
341
+ ci_sub = p_ci.add_subparsers(dest="ci_command", required=True)
342
+
343
+ p_ci_install = ci_sub.add_parser("install", help="Copy a CI template into this project's conventional CI path")
344
+ p_ci_install.add_argument("target", help="github | azure-devops")
345
+ p_ci_install.add_argument("project_root", nargs="?", default=".", help="Target project directory (default: cwd)")
346
+ p_ci_install.add_argument("--force", action="store_true", help="Overwrite an existing CI file")
347
+ p_ci_install.set_defaults(func=cmd_ci_install)
348
+
349
+ return parser
350
+
351
+
352
+ def main(argv=None):
353
+ parser = build_parser()
354
+ args = parser.parse_args(argv)
355
+ sys.exit(args.func(args))
356
+
357
+
358
+ if __name__ == "__main__":
359
+ main()
@@ -0,0 +1,179 @@
1
+ Metadata-Version: 2.4
2
+ Name: aidd-cli
3
+ Version: 0.1.0
4
+ Summary: AIDD — a methodology for working with AI coding agents (CLI distribution)
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/quimhen/aidd
7
+ Project-URL: Repository, https://github.com/quimhen/aidd
8
+ Project-URL: Issues, https://github.com/quimhen/aidd/issues
9
+ Project-URL: Documentation, https://github.com/quimhen/aidd/blob/master/docs/PIPELINE.md
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Software Development :: Build Tools
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Dynamic: license-file
25
+
26
+ # AIDD — AI-Driven Development
27
+
28
+ **A methodology for working with AI coding agents**, not another AI coding agent itself. AIDD
29
+ makes an agent search before it creates, plan out loud before it builds, and get reviewed by
30
+ someone other than itself before a change is called done — automatically, on Claude Code, OpenCode,
31
+ Codex, Gemini CLI, and any other tool that can read a markdown file and run a shell command.
32
+
33
+ ## The problem
34
+
35
+ AI coding agents are fast at writing code and bad at knowing what already exists. Left alone, they
36
+ duplicate specs nobody asked for, re-explain a flow in three paragraphs instead of drawing it, ship
37
+ a fix that fabricates success instead of actually calling the real backend, and grade their own
38
+ homework when asked to review it. AIDD is the set of habits that stops that — enforced by hooks
39
+ where the tool allows it, followed as a written discipline everywhere else.
40
+
41
+ ## What it does
42
+
43
+ - **Searches before creating.** Every request runs against a compact, auto-built graph of every
44
+ existing spec (`specs/index.toon`) before anything new gets created — a match means "amend this,"
45
+ not "start over."
46
+ - **Plans out loud.** Ambiguity gets resolved as an explicit question before code is written, not
47
+ discovered after a review.
48
+ - **Ships in small, reviewable pieces.** One code, one file, one PR — a wrong pass costs one edit,
49
+ not a rewrite.
50
+ - **Never lets the implementer grade its own work.** Step 6's review must come from a separate
51
+ agent dispatch. On Claude Code this is an actual technical gate
52
+ (`hooks/require_independent_audit.py`), not just a rule stated in a doc.
53
+ - **Works the same across tools.** One methodology (`skill/AIDD.md`), thin adapters per tool — no
54
+ relearning the process when the assistant changes. For Claude Code, OpenCode, and Codex, that's
55
+ a native skill/AGENTS.md pointer; for Gemini CLI, Cursor, Windsurf, Cline, and GitHub Copilot,
56
+ `generate_adapters.py` renders each one's own native command-file format straight from
57
+ `commands/aidd-*.md` — one source, no per-agent copy to keep in sync. Both the issue-tracker
58
+ providers and these adapter targets are auto-discovered extensions (see
59
+ [`docs/EXTENDING.md`](docs/EXTENDING.md)), so a project can add its own without forking this repo.
60
+ - **Has a charter that's actually checked.** Project-wide rules split into judgment calls
61
+ (prose) and checkable ones (a pattern + glob table `check_charter.py` runs for real) — not
62
+ a principles doc trusted to memory. Run against a real production project, it caught two
63
+ stale claims in that project's own hand-written notes about specific libraries being unused
64
+ (both false, verified in seconds) and a third that turned out far worse than self-rated
65
+ (340 real violations of a rule logged as low-severity).
66
+ - **Verifies its own map before planning against it.** The spec graph is parsed mechanically
67
+ (fast, cheap), which also means it can misparse a renamed code or a stale relationship — so a
68
+ rebuild dispatches an independent Graph Coherence Auditor before `plan.md`/`tasks.md` build on
69
+ the new edges. Enforced by a hook pair, not a step an agent could skip under time pressure.
70
+ - **Syncs to GitHub, Azure DevOps, or Bitbucket — not just markdown.** An approved `tasks.md`
71
+ becomes real, trackable issues via `tasks_to_issues.py --provider {github,azure_devops,
72
+ bitbucket}` — dry-run by default, never duplicates on re-run. It stays in sync from there:
73
+ `aidd tracker sync` diffs (or writes, with `--apply`) `tasks.md`'s Status column against live
74
+ tracker status, and `aidd tracker link-pr` attaches an opened PR's URL back to its task's
75
+ tracker issue and `tasks.md` row. CI templates for both trackers ship under
76
+ `skill/templates/ci/`, installed with `aidd ci install {github,azure-devops}`.
77
+ - **Has a package-install mechanism, kept to the load-bearing parts — not yet a third-party
78
+ ecosystem.** `catalog/` is the marketplace *mechanism*: packages (templates, agent adapters,
79
+ issue-tracker providers, hooks) install into *your* project with `aidd marketplace install
80
+ <id>`, content-hashed so `remove` never discards a file you hand-edited since. A
81
+ `provider`/`adapter`/`hook` package lands under `.aidd/extensions/<id>/` and is
82
+ auto-discovered from there — no code change to this repo needed to use it. Structural
83
+ validation runs in CI on every submission; a maintainer still reviews and merges each one by
84
+ hand — see `catalog/README.md`. Today that catalog holds exactly one package, first-party
85
+ (`hotfix-report`); zero third-party submissions have been merged yet — the mechanism is built
86
+ and tested, the ecosystem it's built for doesn't exist yet. Manage what's discovered
87
+ (first-party or project-local) with `aidd extensions list|info <id>|enable <id>|disable <id>`
88
+ — see [`docs/EXTENDING.md`](docs/EXTENDING.md).
89
+
90
+ ## What's in this repo
91
+
92
+ - **`skill/`** — the Claude Code skill: `SKILL.md`, enforcement hooks (`hooks/`), and every
93
+ script/template (`scripts/`, `templates/`). `skill/AIDD.md` is the tool-agnostic methodology
94
+ core every other adapter — including this repo's own CLI — points back to.
95
+ - **`aidd/`** — the CLI (`pip install -e .` → the `aidd` command): a thin dispatcher over
96
+ `skill/scripts/`, for a human at a terminal or a CI job, no AI agent required.
97
+ - **`commands/`** — the eight `/aidd-*` pipeline-stage commands for Claude Code.
98
+ - **`adapters/`** — drop-in adapters for other agent tools (OpenCode skill + plugin, an
99
+ `AGENTS.md` snippet for Codex and others, a `GEMINI.md` pointer) plus `dot-aidd/`, the portable
100
+ `.aidd/` bundle (methodology + scripts + templates, no Claude-specific pieces) any project
101
+ installs once and every adapter reads from. See `adapters/README.md` for the install steps.
102
+ - **`catalog/`** — the marketplace mechanism: `schema.json`, two registries (`catalog.json`
103
+ first-party, currently one package; `catalog.community.json` third-party, currently empty),
104
+ and `packages/<id>/` folders. Installed/searched via `skill/scripts/marketplace.py` (or `aidd
105
+ marketplace ...`), validated in CI by `skill/scripts/validate_catalog_entry.py`. See
106
+ `catalog/README.md` and `catalog/CONTRIBUTING.md`.
107
+ - **`tests/`** — the stdlib `unittest` suite (zero dependencies, `python -m unittest discover -s
108
+ tests`), run on every push/PR by `.github/workflows/test.yml` (and `catalog-validate.yml` for
109
+ anything touching `catalog/`).
110
+
111
+ ## Install (Claude Code)
112
+
113
+ ```bash
114
+ cp -r skill ~/.claude/skills/aidd
115
+ python ~/.claude/skills/aidd/scripts/install_hooks.py
116
+ ```
117
+
118
+ ## Install (the CLI — for a terminal or CI, no AI agent needed)
119
+
120
+ ```bash
121
+ git clone https://github.com/quimhen/aidd.git && cd aidd
122
+ pip install -e .
123
+ aidd init /path/to/your/project # installs the .aidd/ bundle there
124
+ aidd search "login" # search the spec graph
125
+ aidd check specs/001-login/ # mechanical gap-check
126
+ aidd check-charter . # run charter.md's checkable rules
127
+ aidd tasks-to-issues specs/001-login/tasks.md --apply # sync tasks (github by default)
128
+ aidd tasks-to-issues specs/001-login/tasks.md --provider azure_devops --org ... --project ... --apply
129
+ aidd adapters generate all /path/to/your/project # native commands for Gemini CLI, Cursor, Windsurf, Cline, Copilot
130
+ aidd marketplace list # browse installable third-party packages
131
+ aidd marketplace install hotfix-report /path/to/your/project
132
+ aidd extensions list # discovered provider/adapter/hook extensions
133
+ aidd tracker sync specs/001-login/tasks.md --provider github --repo owner/repo # dry-run status diff
134
+ aidd tracker link-pr specs/001-login/tasks.md --pr-url ... --branch ... --apply
135
+ aidd ci install github /path/to/your/project # install the GitHub Actions CI template
136
+ ```
137
+
138
+ Not yet published to PyPI — install from a clone for now.
139
+
140
+ ## Install (other tools)
141
+
142
+ See `adapters/README.md`.
143
+
144
+ ## Documentation
145
+
146
+ - [**Why AIDD**](docs/WHY-AIDD.md) — what changes for you, in plain language, with the measured
147
+ numbers.
148
+ - [**Pipeline reference**](docs/PIPELINE.md) — the full technical breakdown: the code system, the
149
+ spec graph, every step, the enforcement hooks.
150
+ - [**FAQ**](docs/FAQ.md) — common questions. Have one that's not there? Open an
151
+ [issue](../../issues) or a [discussion](../../discussions).
152
+ - [**Extending AIDD**](docs/EXTENDING.md) — the three extension seams (issue tracker
153
+ providers and multi-agent adapter targets, both auto-discovered from
154
+ `skill/extensions/**/manifest.json` or `.aidd/extensions/**/manifest.json`, plus
155
+ charter checkable rules), and how they relate to the marketplace (`catalog/`).
156
+ - [**Consulting**](docs/CONSULTING.md) — if your team wants help adopting AIDD.
157
+
158
+ ## Status
159
+
160
+ Early — the core pipeline, the search/graph tools, the charter checker, the graph-coherence
161
+ gate, the issue-tracker sync (GitHub/Azure DevOps/Bitbucket, plus bidirectional status sync
162
+ via `aidd tracker sync` and PR<->task linking via `aidd tracker link-pr`), CI templates and
163
+ `aidd ci install`, the Claude Code hooks (nine of them, including the independent-audit and
164
+ graph-coherence gates), the multi-agent adapter generator (`generate_adapters.py`, rendering
165
+ Gemini CLI/Cursor/Windsurf/Cline/Copilot commands from one source), the real auto-discovery
166
+ extension registry (`extension_registry.py`, loading provider/adapter/hook extensions from
167
+ `skill/extensions/**/manifest.json` and `.aidd/extensions/**/manifest.json` — see
168
+ `docs/EXTENDING.md`), and the marketplace (`catalog/` + `marketplace.py` +
169
+ `validate_catalog_entry.py`, one first-party package shipped so far: `hotfix-report`) are built,
170
+ tested (stdlib `unittest`, run in CI), and have been run against a real production
171
+ codebase. OpenCode, Codex, and the five generated adapter targets follow the same methodology;
172
+ only the Claude Code hooks currently give it technical teeth. Not yet published to PyPI. The
173
+ marketplace is intentionally not a fully automated accept path: CI validates structure and
174
+ flags anything worth a human's attention, but a maintainer reviews and merges every catalog
175
+ submission by hand — see `catalog/README.md`.
176
+
177
+ ## License
178
+
179
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,8 @@
1
+ aidd/__init__.py,sha256=RGJLvKAoxlfGTTup783pSjKpnA8bjT44MOSatfXDp2Y,459
2
+ aidd/cli.py,sha256=zyLymiqu2ZuxSKEPWMcBNuz2b6_JqmJBrj-njQEXLfE,16237
3
+ aidd_cli-0.1.0.dist-info/licenses/LICENSE,sha256=QWyaZ19DyA6BWgOrnsQeLbu_C4IK30m4Q1Idjjd8rDE,1074
4
+ aidd_cli-0.1.0.dist-info/METADATA,sha256=iHOEWCEu2t_IleITSdfAZzOGoxwqNvHnKHXLBILfBzo,11436
5
+ aidd_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
6
+ aidd_cli-0.1.0.dist-info/entry_points.txt,sha256=Dv0zax7wAl3v5BpttStFnukik23DOYstt-gasaX8N28,39
7
+ aidd_cli-0.1.0.dist-info/top_level.txt,sha256=RivklEgpYJ8M9z2CGKO_ZMU-kgzz5NPB8U3nEL3jWLI,5
8
+ aidd_cli-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ aidd = aidd.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AIDD contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ aidd