Summary
The current CLI assumes that project-level skills and squads always live at the repository root:
That breaks projects organized by department, where the canonical layout is:
marketing/skills/
marketing/squads/
There is also a second issue in runs: it treats any directory under output/ as a run, which causes false positives for asset folders such as output/images/ and output/slides/.
Current behavior
npx opensquad skills only reads skills/
npx opensquad runs <squad> only reads squads/
npx opensquad runs <squad> treats any folder in output/ as a run id
Expected behavior
- Prefer
marketing/skills/ when it exists, with fallback to skills/
- Prefer
marketing/squads/ when it exists, with fallback to squads/
- Only treat real run directories as runs, for example
YYYY-MM-DD-HHmmss and YYYY-MM-DD-HHmmss-N
Minimal reproduction
- Create a project using:
marketing/skills/example-skill/SKILL.md
marketing/squads/example-squad/output/images/
marketing/squads/example-squad/output/slides/
- Run
npx opensquad skills
- Run
npx opensquad runs example-squad
Observed today:
skills does not find example-skill
runs does not resolve the squad path unless the project also keeps a legacy squads/ alias
- when the squad path is resolved,
images and slides can be reported as if they were runs
Environment
- OS: macOS Darwin 25.4.0
- Node.js:
v24.11.1
- npm:
11.6.2
- IDE: Codex / Claude Code-compatible local environment
Proposed fix
Keep the upstream change minimal and runtime-only:
- update
src/skills.js to resolve marketing/skills/ first, then fallback to skills/
- update
src/runs.js to resolve marketing/squads/ first, then fallback to squads/
- update
src/runs.js to ignore non-run directories inside output/
I already prepared a patch for opensquad@0.1.15 plus matching tests for skills and runs.
Notes
- This preserves backward compatibility for existing root-based projects.
- I intentionally did not include template or documentation changes in the patch, to keep the proposal narrowly scoped to CLI/runtime behavior first.
- I checked the current upstream
master branch before preparing this report: src/skills.js still resolves only skills/, and src/runs.js still resolves only squads/ and lists every output/ subdirectory as a run.
Summary
The current CLI assumes that project-level skills and squads always live at the repository root:
skills/squads/That breaks projects organized by department, where the canonical layout is:
marketing/skills/marketing/squads/There is also a second issue in
runs: it treats any directory underoutput/as a run, which causes false positives for asset folders such asoutput/images/andoutput/slides/.Current behavior
npx opensquad skillsonly readsskills/npx opensquad runs <squad>only readssquads/npx opensquad runs <squad>treats any folder inoutput/as a run idExpected behavior
marketing/skills/when it exists, with fallback toskills/marketing/squads/when it exists, with fallback tosquads/YYYY-MM-DD-HHmmssandYYYY-MM-DD-HHmmss-NMinimal reproduction
marketing/skills/example-skill/SKILL.mdmarketing/squads/example-squad/output/images/marketing/squads/example-squad/output/slides/npx opensquad skillsnpx opensquad runs example-squadObserved today:
skillsdoes not findexample-skillrunsdoes not resolve the squad path unless the project also keeps a legacysquads/aliasimagesandslidescan be reported as if they were runsEnvironment
v24.11.111.6.2Proposed fix
Keep the upstream change minimal and runtime-only:
src/skills.jsto resolvemarketing/skills/first, then fallback toskills/src/runs.jsto resolvemarketing/squads/first, then fallback tosquads/src/runs.jsto ignore non-run directories insideoutput/I already prepared a patch for
opensquad@0.1.15plus matching tests forskillsandruns.Notes
masterbranch before preparing this report:src/skills.jsstill resolves onlyskills/, andsrc/runs.jsstill resolves onlysquads/and lists everyoutput/subdirectory as a run.