diff --git a/AGENTS.md b/AGENTS.md index 052aded9d..3ce614743 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,10 +41,12 @@ Project docs, memory, specs, and plans live in `aidd_docs/`. @aidd_docs/memory/architecture.md -@aidd_docs/memory/browsing.md +@aidd_docs/memory/backlog.md +@aidd_docs/memory/cli.md @aidd_docs/memory/codebase-map.md @aidd_docs/memory/coding-assertions.md @aidd_docs/memory/deployment.md +@aidd_docs/memory/ecosystem.md @aidd_docs/memory/project-brief.md @aidd_docs/memory/testing.md @aidd_docs/memory/vcs.md diff --git a/CLAUDE.md b/CLAUDE.md index a61cf56d6..25457755a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,10 +41,12 @@ Project docs, memory, specs, and plans live in `aidd_docs/`. @aidd_docs/memory/architecture.md -@aidd_docs/memory/browsing.md +@aidd_docs/memory/backlog.md +@aidd_docs/memory/cli.md @aidd_docs/memory/codebase-map.md @aidd_docs/memory/coding-assertions.md @aidd_docs/memory/deployment.md +@aidd_docs/memory/ecosystem.md @aidd_docs/memory/project-brief.md @aidd_docs/memory/testing.md @aidd_docs/memory/vcs.md diff --git a/aidd_docs/memory/backlog.md b/aidd_docs/memory/backlog.md new file mode 100644 index 000000000..b152a7711 --- /dev/null +++ b/aidd_docs/memory/backlog.md @@ -0,0 +1,44 @@ +# Backlog + +## Supports + +| Support | Authority for | Role | +| --- | --- | --- | +| GitHub Issues | the work items, their type and their scope | where a change is agreed before a branch exists | +| AIDD Roadmap board (org project 8) | order, status, and what ships next | the single source of truth for the roadmap | +| Milestones | themes | a theme with a Thursday due date; no milestone means backlog | +| GitHub Discussions | ideas and their upvotes | where an idea is weighed before it becomes an issue | +| `aidd_docs/` task documents | the local plans, specs and reviews behind an issue | read by `aidd kanban`, never a substitute for the issue | + +## Representation + +| Artifact | Support | Native representation | +| --- | --- | --- | +| Feature | GitHub Issues | issue type `Feature`, form ๐ŸŒฑ Quick Contribution | +| Bug | GitHub Issues | issue type `Bug`, form ๐Ÿ› Bug Report | +| Task | GitHub Issues | issue type `Task`, form ๐Ÿ“‹ Detailed Contribution | +| Theme | Milestones | one milestone, due on a Thursday | +| Idea | GitHub Discussions | a discussion, ranked by ๐Ÿ‘ | + +The form stamps the type; nobody sets it by hand. Labels categorize nothing: one exists only when a bot or a human reads it, and `.github/labels.yml` is their source of truth. + +## Workflow + +| Support | Native status | Meaning | +| --- | --- | --- | +| Roadmap board | Todo | agreed, not started | +| Roadmap board | In review | a pull request is open | +| Roadmap board | Done | merged | + +The board is moved by hand, by a human or an agent through `gh`. No workflow advances it. + +## Planning + +- Priority: set by a community vote, mechanism in `GOVERNANCE.md`. +- Iteration: weekly, a milestone per theme due on a Thursday. +- Milestone: closed automatically once all its issues are, by `.github/workflows/close-finished-milestones.yml`. + +## Relations + +- An issue's branch and pull request carry the routing: the branch prefix decides the target, per `vcs.md`. +- A `aidd_docs/` task folder is grouped by its parent document (`plan.md`, then `master-plan.md`, then `spec.md`), and a sub-document's status never moves that parent. diff --git a/aidd_docs/memory/browsing.md b/aidd_docs/memory/browsing.md deleted file mode 100644 index 393f81fa3..000000000 --- a/aidd_docs/memory/browsing.md +++ /dev/null @@ -1,5 +0,0 @@ -# Browser Setup - -- **Browsing Tool**: Playwright MCP (configured in `.playwright-mcp/`) -- **Starting URL**: None โ€” framework has no web UI; used for testing downstream projects -- **Authentication**: N/A diff --git a/aidd_docs/memory/cli.md b/aidd_docs/memory/cli.md new file mode 100644 index 000000000..34e7bf6c7 --- /dev/null +++ b/aidd_docs/memory/cli.md @@ -0,0 +1,24 @@ +# CLI + +The `aidd` binary, built from `cli/` and published to npm. + +## Commands + +- `setup`, `ai`, `ide`: install and refresh AI tool configurations in a target project. +- `framework`: build a target-native distribution of this repo (`--target `, `--out`, `--flat`). The release workflow calls it at a pinned version, so a CLI release never silently changes framework dist output. +- `plugin`, `marketplace`: add, list, search, update and remove plugins and the marketplaces they come from. +- `kanban`: render `aidd_docs/` task frontmatter as status columns, interactive or `list --json`. Source lives in `kanban/`, bundled from source at build time. +- `auth`, `status`, `doctor`, `clean`, `restore`, `update`, `self-update`: credentials, diagnosis, and upkeep. + +## Interface + +- Commands register on one `commander` program in `cli/src/cli.ts`; each has its own file under `application/commands/`. +- `--verbose` is global. Read the surface from `aidd --help`, never from a copy. +- Only commands already paying for network I/O carry the update check, listed as `ONLINE_COMMAND_PATHS` in `cli/src/cli.ts`. +- `framework build` refuses to run when `--out` sits inside `--source`. + +## Distribution + +- `bin.aidd` points at `dist/cli.js`, bundled by `tsup` under a bundle size budget the build enforces (`bundleBudgetKB`). +- Published to npm by OIDC trusted publishing when release-please releases the `cli` path. The GitHub Packages push runs first and is best-effort: it never fails the job. +- `kanban/` never imports from `cli/`: everything it needs arrives through `KanbanCommandDeps` at registration. diff --git a/aidd_docs/memory/ecosystem.md b/aidd_docs/memory/ecosystem.md new file mode 100644 index 000000000..7ac3ad64a --- /dev/null +++ b/aidd_docs/memory/ecosystem.md @@ -0,0 +1,27 @@ +# Ecosystem + +```mermaid +flowchart LR + Human([Human]) + Agent([Agent]) + App([App]) + GitHub["GitHub ยท vcs.md"] + Board["Roadmap project board ยท backlog.md"] + Npm["npm registry"] + Packages["GitHub Packages"] + Discord["Discord ยท human only"] + ReleasePlease["release-please"] + Dependabot["Dependabot"] + + Agent -- cli --> GitHub + Agent -- cli --> Board + Human -- cli --> Board + App -- http --> GitHub + App -- http --> Npm + Human -- web --> Discord + + Dependabot -- "dependency update PR" --> GitHub + ReleasePlease -- "merge on main" --> GitHub + GitHub -- "release created" --> Npm + GitHub -- "release created" --> Packages +```