Why use it: You clone AREX-Skill to change the tool, not to use it.
What it produces: cli/dist/ built, one disco command linked from the checkout, and a gate tree that ran green.
This track is independent of
01–08. No need to install a release build first.
1. Code map (this is where it is easiest to get lost)
AREX-Skill/
├── cli/ ← package npm @arex-skill/disco
│ ├── package.json ← MANIFEST DUY NHẤT của cả repo
│ ├── npm-shrinkwrap.json ← dependency được ghim
│ ├── vitest.config.ts ← root test trỏ về packages/coding-agent
│ ├── tsconfig.build.json / tsconfig.examples.json
│ ├── AGENTS.md ← luật bảo trì provenance/release
│ ├── docs/ ← 30+ trang tài liệu CLI
│ ├── scripts/ ← upstream-provenance · verify-package · copy-assets
│ └── packages/coding-agent/
│ ├── UPSTREAM_MANIFEST.json ← kiểm kê provenance
│ ├── src/
│ │ ├── cli.ts ← entry process (bin → dist/cli.js)
│ │ ├── main.ts ← điều phối, 33KB
│ │ ├── config.ts ← APP_NAME · CONFIG_DIR_NAME · đường dẫn agent dir
│ │ ├── package-manager-cli.ts ← install/remove/update/list/config
│ │ ├── cli/args.ts ← PARSER CỜ + printHelp()
│ │ ├── cli/repo-skills.ts ← subcommand repo-skills
│ │ ├── core/repo-skills-library-manager.ts ← clone/adopt/update/drift
│ │ ├── core/slash-commands.ts ← 24 lệnh chat built-in
│ │ ├── modes/print-mode.ts ← -p / --mode json, exit code
│ │ ├── modes/interactive/ ← TUI (interactive-mode.ts ~207KB)
│ │ └── disco/skills/ ← 17 skill bundled (15 meta + 1 operating + 1 shared)
│ └── test/ ← ~60 file test vitest
├── skills/repositories/ ← thư viện runtime 1000 skill + router
├── docs/ ← tài liệu cấp repo (song ngữ EN/zh)
├── examples/ ← export session HTML + starter TOML
└── scripts/ ← installer + build-from-source-link.sh
There is no manifest besides cli/package.json — the repo is not a monorepo with workspaces.
2. Dev loop
cd cli
npm ci --ignore-scripts # dùng npm-shrinkwrap.json đã ghim
npm run typecheck # tsc --noEmit -p tsconfig.build.json
npm test # vitest --run + node --test scripts/upstream-provenance.test.mjs
npm run build # clean + tsc + copy-assets + chmod +x dist/cli.js dist/rpc-entry.js
Run a single test file:
cd cli
npx vitest --run packages/coding-agent/test/disco-mode-skills.test.ts
Tests run with DISCO_OFFLINE=1, PI_OFFLINE=1, fileParallelism: false, timeout 30s, reporter dot (vitest.config.ts). No parallelization — don't be surprised when it is slow.
Link the dev build as a global disco command:
cd ..
bash scripts/build-from-source-link.sh
3. Full gate before publishing
cd cli
npm run prepublishOnly
It runs 7 tasks sequentially, stopping wherever it breaks:
verify:provenance → typecheck → test → test:examples → verify:rpiv-todo-contract → build → verify:package
| Script | Real command | What it guards |
|---|---|---|
verify:provenance |
node scripts/upstream-provenance.mjs --check |
UPSTREAM_MANIFEST.json matches files on disk. Local-only, no Pi checkout needed |
typecheck |
tsc --noEmit -p tsconfig.build.json |
Types |
test |
vitest --run + node --test scripts/upstream-provenance.test.mjs |
Behavior |
test:examples |
tsc --noEmit -p tsconfig.examples.json |
Examples in examples/ still compile |
verify:rpiv-todo-contract |
node scripts/verify-rpiv-todo-contract.mjs |
RPIV TODO contract |
build |
as above | Output to dist/ |
verify:package |
node scripts/verify-package.mjs |
Audit exactly which files are packaged |
Try packaging:
cd cli
npm publish --dry-run --ignore-scripts
4. Provenance — the most fragile part
Inventory scope: packages/coding-agent/src, packages/coding-agent/test, docs, examples.
cd cli
# Sau khi CỐ Ý sửa file đã có trong 4 thư mục trên:
npm run refresh:provenance
# Khi THÊM file mới do DisCo sở hữu — phải duyệt tường minh từng file:
npm run refresh:provenance -- --add-local docs/dynamic-workflows.md
Rules (from cli/AGENTS.md):
- Refresh must not silently swallow foreign files, accept missing declared files, or change upstream hash/mapping. Read the manifest diff after refreshing.
- The full upstream workflow is only used when the Pi baseline actually changes:
Needs a clean Pi checkout, pinned to the correct repo/tag/commit. Do not clean/modify the Pi checkout externally just so a release cannode scripts/upstream-provenance.mjs --write --upstream-root /path/to/picli. scripts/build-from-source-link.shis smoke build/link, not a release gate.- Git worktree does not need to be clean to release npm, but you should commit/tag the reviewed state so it can be traced back to the correct revision.
5. Modify bundled skills
Single source of truth: cli/packages/coding-agent/src/disco/skills/.
When modifying:
- Declare clearly the expected input and output;
- Ask for user confirmation at expensive or destructive points, unless the user has already authorized it;
- Keep environment changes isolated;
- Separate runtime-generated content from tests and reports;
- Decouple installing the meta-skill from deploying the graph it generates;
- The repo graph goes through a specialized import path
~/.disco/agent/skills/repositories/repo-skills/+ rebuild sibling routers — do not push routing metadata through the general graph importer; - Update
cli/packages/coding-agent/src/disco/skills/README.mdwhen the name/path/default/boundary changes; - Modify the generator and the template at the same time. Router behavior rendered by
update_repo_skills_router.mjsis rendered by must not be changed only in the committed Markdown file.
The bundled test skill sits right next to it: cli/packages/coding-agent/src/disco/skills/*.test.ts (9 files, e.g. export_repo_skills_to_agent.test.ts, skill-role-contracts.test.ts).
6. What to test when touching discovery/routing
According to CONTRIBUTING.md, changes to the skill discovery & routing path must prove:
- hidden skills are managed registered but do not leak into the initial prompt;
- the live router overrides the bundled fallback;
- skills of a project that is not trusted are not loaded;
- skills from installed packages remain usable.
7. Installer release assets
The installer at the repo root is published as a GitHub Release asset, not included in the npm tarball:
python3 scripts/prepare-disco-release-assets.py
Write out dist/disco-release-assets/: install-disco.sh, install-disco.ps1, SHA256SUMS, release-metadata.json. Attach the 2 installer files + SHA256SUMS to the corresponding GitHub Release, verify the URL releases/latest/download is stable before updating public docs. The standard npm release helper prepares these files but never uploads or creates a GitHub Release on its own.
8. Pitfalls
- The repo has no CI. There is no
.github/workflows/— every gate must be run manually.npm run prepublishOnlyis the closest thing to "CI". - Do not manually edit
dist/or the runtime assets of the standalone binary as if they were source. - Bilingual docs. The root README, installation, architecture, disco-meta-skills, refreshing-repo-skills, CONTRIBUTING, and skills/README are EN/zh pairs — changing one side requires changing the other in the same change.
repository-catalog.mdweighs 673KB — a shared data page covering 1000 roots and 2209 memberships. When changing the catalog, keep the counts, grouping, paths, and summary section in the Chinese README in sync.- Node must be >= 22.19.0. Lower versions may
npm cibut break at runtime.
9. Drift bugs found (read the code, not the README)
docs/disco-workflows.md and cli/docs/packages.md (section Mode Targeting) both document:
disco install <source> --for creator|researcher|both|default
The flag --for does not exist in the parser. package-manager-cli.ts has no branch that catches --for; it falls into invalidOption and the command prints:
Unknown option --for for "install".
then process.exitCode = 1. The command's official usage string is disco install <source> [-l] [--approve|--no-approve]. This is a case of docs ahead of code (or code having fallen behind) — a worthwhile PR.
Next step
10-contributor-dong-gop-skill.md if you contribute skill rather than CLI code.