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 +10 -0
- aidd/cli.py +359 -0
- aidd_cli-0.1.0.dist-info/METADATA +179 -0
- aidd_cli-0.1.0.dist-info/RECORD +8 -0
- aidd_cli-0.1.0.dist-info/WHEEL +5 -0
- aidd_cli-0.1.0.dist-info/entry_points.txt +2 -0
- aidd_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
- aidd_cli-0.1.0.dist-info/top_level.txt +1 -0
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,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
|