aidd-cli 0.1.0__tar.gz
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_cli-0.1.0/LICENSE +21 -0
- aidd_cli-0.1.0/PKG-INFO +179 -0
- aidd_cli-0.1.0/README.md +154 -0
- aidd_cli-0.1.0/aidd/__init__.py +10 -0
- aidd_cli-0.1.0/aidd/cli.py +359 -0
- aidd_cli-0.1.0/aidd_cli.egg-info/PKG-INFO +179 -0
- aidd_cli-0.1.0/aidd_cli.egg-info/SOURCES.txt +25 -0
- aidd_cli-0.1.0/aidd_cli.egg-info/dependency_links.txt +1 -0
- aidd_cli-0.1.0/aidd_cli.egg-info/entry_points.txt +2 -0
- aidd_cli-0.1.0/aidd_cli.egg-info/top_level.txt +1 -0
- aidd_cli-0.1.0/pyproject.toml +38 -0
- aidd_cli-0.1.0/setup.cfg +4 -0
- aidd_cli-0.1.0/tests/test_check_charter.py +151 -0
- aidd_cli-0.1.0/tests/test_check_spec.py +129 -0
- aidd_cli-0.1.0/tests/test_dot_aidd_mirror.py +370 -0
- aidd_cli-0.1.0/tests/test_extension_providers.py +427 -0
- aidd_cli-0.1.0/tests/test_find_spec.py +239 -0
- aidd_cli-0.1.0/tests/test_generate_adapters.py +202 -0
- aidd_cli-0.1.0/tests/test_hooks.py +375 -0
- aidd_cli-0.1.0/tests/test_install_ci.py +108 -0
- aidd_cli-0.1.0/tests/test_install_hooks.py +81 -0
- aidd_cli-0.1.0/tests/test_link_pr_to_task.py +196 -0
- aidd_cli-0.1.0/tests/test_marketplace.py +280 -0
- aidd_cli-0.1.0/tests/test_research_project.py +110 -0
- aidd_cli-0.1.0/tests/test_sync_issues.py +167 -0
- aidd_cli-0.1.0/tests/test_tasks_to_issues.py +185 -0
- aidd_cli-0.1.0/tests/test_validate_catalog_entry.py +185 -0
aidd_cli-0.1.0/LICENSE
ADDED
|
@@ -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.
|
aidd_cli-0.1.0/PKG-INFO
ADDED
|
@@ -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).
|
aidd_cli-0.1.0/README.md
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# AIDD — AI-Driven Development
|
|
2
|
+
|
|
3
|
+
**A methodology for working with AI coding agents**, not another AI coding agent itself. AIDD
|
|
4
|
+
makes an agent search before it creates, plan out loud before it builds, and get reviewed by
|
|
5
|
+
someone other than itself before a change is called done — automatically, on Claude Code, OpenCode,
|
|
6
|
+
Codex, Gemini CLI, and any other tool that can read a markdown file and run a shell command.
|
|
7
|
+
|
|
8
|
+
## The problem
|
|
9
|
+
|
|
10
|
+
AI coding agents are fast at writing code and bad at knowing what already exists. Left alone, they
|
|
11
|
+
duplicate specs nobody asked for, re-explain a flow in three paragraphs instead of drawing it, ship
|
|
12
|
+
a fix that fabricates success instead of actually calling the real backend, and grade their own
|
|
13
|
+
homework when asked to review it. AIDD is the set of habits that stops that — enforced by hooks
|
|
14
|
+
where the tool allows it, followed as a written discipline everywhere else.
|
|
15
|
+
|
|
16
|
+
## What it does
|
|
17
|
+
|
|
18
|
+
- **Searches before creating.** Every request runs against a compact, auto-built graph of every
|
|
19
|
+
existing spec (`specs/index.toon`) before anything new gets created — a match means "amend this,"
|
|
20
|
+
not "start over."
|
|
21
|
+
- **Plans out loud.** Ambiguity gets resolved as an explicit question before code is written, not
|
|
22
|
+
discovered after a review.
|
|
23
|
+
- **Ships in small, reviewable pieces.** One code, one file, one PR — a wrong pass costs one edit,
|
|
24
|
+
not a rewrite.
|
|
25
|
+
- **Never lets the implementer grade its own work.** Step 6's review must come from a separate
|
|
26
|
+
agent dispatch. On Claude Code this is an actual technical gate
|
|
27
|
+
(`hooks/require_independent_audit.py`), not just a rule stated in a doc.
|
|
28
|
+
- **Works the same across tools.** One methodology (`skill/AIDD.md`), thin adapters per tool — no
|
|
29
|
+
relearning the process when the assistant changes. For Claude Code, OpenCode, and Codex, that's
|
|
30
|
+
a native skill/AGENTS.md pointer; for Gemini CLI, Cursor, Windsurf, Cline, and GitHub Copilot,
|
|
31
|
+
`generate_adapters.py` renders each one's own native command-file format straight from
|
|
32
|
+
`commands/aidd-*.md` — one source, no per-agent copy to keep in sync. Both the issue-tracker
|
|
33
|
+
providers and these adapter targets are auto-discovered extensions (see
|
|
34
|
+
[`docs/EXTENDING.md`](docs/EXTENDING.md)), so a project can add its own without forking this repo.
|
|
35
|
+
- **Has a charter that's actually checked.** Project-wide rules split into judgment calls
|
|
36
|
+
(prose) and checkable ones (a pattern + glob table `check_charter.py` runs for real) — not
|
|
37
|
+
a principles doc trusted to memory. Run against a real production project, it caught two
|
|
38
|
+
stale claims in that project's own hand-written notes about specific libraries being unused
|
|
39
|
+
(both false, verified in seconds) and a third that turned out far worse than self-rated
|
|
40
|
+
(340 real violations of a rule logged as low-severity).
|
|
41
|
+
- **Verifies its own map before planning against it.** The spec graph is parsed mechanically
|
|
42
|
+
(fast, cheap), which also means it can misparse a renamed code or a stale relationship — so a
|
|
43
|
+
rebuild dispatches an independent Graph Coherence Auditor before `plan.md`/`tasks.md` build on
|
|
44
|
+
the new edges. Enforced by a hook pair, not a step an agent could skip under time pressure.
|
|
45
|
+
- **Syncs to GitHub, Azure DevOps, or Bitbucket — not just markdown.** An approved `tasks.md`
|
|
46
|
+
becomes real, trackable issues via `tasks_to_issues.py --provider {github,azure_devops,
|
|
47
|
+
bitbucket}` — dry-run by default, never duplicates on re-run. It stays in sync from there:
|
|
48
|
+
`aidd tracker sync` diffs (or writes, with `--apply`) `tasks.md`'s Status column against live
|
|
49
|
+
tracker status, and `aidd tracker link-pr` attaches an opened PR's URL back to its task's
|
|
50
|
+
tracker issue and `tasks.md` row. CI templates for both trackers ship under
|
|
51
|
+
`skill/templates/ci/`, installed with `aidd ci install {github,azure-devops}`.
|
|
52
|
+
- **Has a package-install mechanism, kept to the load-bearing parts — not yet a third-party
|
|
53
|
+
ecosystem.** `catalog/` is the marketplace *mechanism*: packages (templates, agent adapters,
|
|
54
|
+
issue-tracker providers, hooks) install into *your* project with `aidd marketplace install
|
|
55
|
+
<id>`, content-hashed so `remove` never discards a file you hand-edited since. A
|
|
56
|
+
`provider`/`adapter`/`hook` package lands under `.aidd/extensions/<id>/` and is
|
|
57
|
+
auto-discovered from there — no code change to this repo needed to use it. Structural
|
|
58
|
+
validation runs in CI on every submission; a maintainer still reviews and merges each one by
|
|
59
|
+
hand — see `catalog/README.md`. Today that catalog holds exactly one package, first-party
|
|
60
|
+
(`hotfix-report`); zero third-party submissions have been merged yet — the mechanism is built
|
|
61
|
+
and tested, the ecosystem it's built for doesn't exist yet. Manage what's discovered
|
|
62
|
+
(first-party or project-local) with `aidd extensions list|info <id>|enable <id>|disable <id>`
|
|
63
|
+
— see [`docs/EXTENDING.md`](docs/EXTENDING.md).
|
|
64
|
+
|
|
65
|
+
## What's in this repo
|
|
66
|
+
|
|
67
|
+
- **`skill/`** — the Claude Code skill: `SKILL.md`, enforcement hooks (`hooks/`), and every
|
|
68
|
+
script/template (`scripts/`, `templates/`). `skill/AIDD.md` is the tool-agnostic methodology
|
|
69
|
+
core every other adapter — including this repo's own CLI — points back to.
|
|
70
|
+
- **`aidd/`** — the CLI (`pip install -e .` → the `aidd` command): a thin dispatcher over
|
|
71
|
+
`skill/scripts/`, for a human at a terminal or a CI job, no AI agent required.
|
|
72
|
+
- **`commands/`** — the eight `/aidd-*` pipeline-stage commands for Claude Code.
|
|
73
|
+
- **`adapters/`** — drop-in adapters for other agent tools (OpenCode skill + plugin, an
|
|
74
|
+
`AGENTS.md` snippet for Codex and others, a `GEMINI.md` pointer) plus `dot-aidd/`, the portable
|
|
75
|
+
`.aidd/` bundle (methodology + scripts + templates, no Claude-specific pieces) any project
|
|
76
|
+
installs once and every adapter reads from. See `adapters/README.md` for the install steps.
|
|
77
|
+
- **`catalog/`** — the marketplace mechanism: `schema.json`, two registries (`catalog.json`
|
|
78
|
+
first-party, currently one package; `catalog.community.json` third-party, currently empty),
|
|
79
|
+
and `packages/<id>/` folders. Installed/searched via `skill/scripts/marketplace.py` (or `aidd
|
|
80
|
+
marketplace ...`), validated in CI by `skill/scripts/validate_catalog_entry.py`. See
|
|
81
|
+
`catalog/README.md` and `catalog/CONTRIBUTING.md`.
|
|
82
|
+
- **`tests/`** — the stdlib `unittest` suite (zero dependencies, `python -m unittest discover -s
|
|
83
|
+
tests`), run on every push/PR by `.github/workflows/test.yml` (and `catalog-validate.yml` for
|
|
84
|
+
anything touching `catalog/`).
|
|
85
|
+
|
|
86
|
+
## Install (Claude Code)
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
cp -r skill ~/.claude/skills/aidd
|
|
90
|
+
python ~/.claude/skills/aidd/scripts/install_hooks.py
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Install (the CLI — for a terminal or CI, no AI agent needed)
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
git clone https://github.com/quimhen/aidd.git && cd aidd
|
|
97
|
+
pip install -e .
|
|
98
|
+
aidd init /path/to/your/project # installs the .aidd/ bundle there
|
|
99
|
+
aidd search "login" # search the spec graph
|
|
100
|
+
aidd check specs/001-login/ # mechanical gap-check
|
|
101
|
+
aidd check-charter . # run charter.md's checkable rules
|
|
102
|
+
aidd tasks-to-issues specs/001-login/tasks.md --apply # sync tasks (github by default)
|
|
103
|
+
aidd tasks-to-issues specs/001-login/tasks.md --provider azure_devops --org ... --project ... --apply
|
|
104
|
+
aidd adapters generate all /path/to/your/project # native commands for Gemini CLI, Cursor, Windsurf, Cline, Copilot
|
|
105
|
+
aidd marketplace list # browse installable third-party packages
|
|
106
|
+
aidd marketplace install hotfix-report /path/to/your/project
|
|
107
|
+
aidd extensions list # discovered provider/adapter/hook extensions
|
|
108
|
+
aidd tracker sync specs/001-login/tasks.md --provider github --repo owner/repo # dry-run status diff
|
|
109
|
+
aidd tracker link-pr specs/001-login/tasks.md --pr-url ... --branch ... --apply
|
|
110
|
+
aidd ci install github /path/to/your/project # install the GitHub Actions CI template
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Not yet published to PyPI — install from a clone for now.
|
|
114
|
+
|
|
115
|
+
## Install (other tools)
|
|
116
|
+
|
|
117
|
+
See `adapters/README.md`.
|
|
118
|
+
|
|
119
|
+
## Documentation
|
|
120
|
+
|
|
121
|
+
- [**Why AIDD**](docs/WHY-AIDD.md) — what changes for you, in plain language, with the measured
|
|
122
|
+
numbers.
|
|
123
|
+
- [**Pipeline reference**](docs/PIPELINE.md) — the full technical breakdown: the code system, the
|
|
124
|
+
spec graph, every step, the enforcement hooks.
|
|
125
|
+
- [**FAQ**](docs/FAQ.md) — common questions. Have one that's not there? Open an
|
|
126
|
+
[issue](../../issues) or a [discussion](../../discussions).
|
|
127
|
+
- [**Extending AIDD**](docs/EXTENDING.md) — the three extension seams (issue tracker
|
|
128
|
+
providers and multi-agent adapter targets, both auto-discovered from
|
|
129
|
+
`skill/extensions/**/manifest.json` or `.aidd/extensions/**/manifest.json`, plus
|
|
130
|
+
charter checkable rules), and how they relate to the marketplace (`catalog/`).
|
|
131
|
+
- [**Consulting**](docs/CONSULTING.md) — if your team wants help adopting AIDD.
|
|
132
|
+
|
|
133
|
+
## Status
|
|
134
|
+
|
|
135
|
+
Early — the core pipeline, the search/graph tools, the charter checker, the graph-coherence
|
|
136
|
+
gate, the issue-tracker sync (GitHub/Azure DevOps/Bitbucket, plus bidirectional status sync
|
|
137
|
+
via `aidd tracker sync` and PR<->task linking via `aidd tracker link-pr`), CI templates and
|
|
138
|
+
`aidd ci install`, the Claude Code hooks (nine of them, including the independent-audit and
|
|
139
|
+
graph-coherence gates), the multi-agent adapter generator (`generate_adapters.py`, rendering
|
|
140
|
+
Gemini CLI/Cursor/Windsurf/Cline/Copilot commands from one source), the real auto-discovery
|
|
141
|
+
extension registry (`extension_registry.py`, loading provider/adapter/hook extensions from
|
|
142
|
+
`skill/extensions/**/manifest.json` and `.aidd/extensions/**/manifest.json` — see
|
|
143
|
+
`docs/EXTENDING.md`), and the marketplace (`catalog/` + `marketplace.py` +
|
|
144
|
+
`validate_catalog_entry.py`, one first-party package shipped so far: `hotfix-report`) are built,
|
|
145
|
+
tested (stdlib `unittest`, run in CI), and have been run against a real production
|
|
146
|
+
codebase. OpenCode, Codex, and the five generated adapter targets follow the same methodology;
|
|
147
|
+
only the Claude Code hooks currently give it technical teeth. Not yet published to PyPI. The
|
|
148
|
+
marketplace is intentionally not a fully automated accept path: CI validates structure and
|
|
149
|
+
flags anything worth a human's attention, but a maintainer reviews and merges every catalog
|
|
150
|
+
submission by hand — see `catalog/README.md`.
|
|
151
|
+
|
|
152
|
+
## License
|
|
153
|
+
|
|
154
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -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"
|