atlas-package-cloner

Files (4)

• SKILL.md
• custom_deps_and_overrides.md · references/
• features_and_replay.md · references/
• start_project.md · references/

SKILL.md (first lines)

# Atlas Package Cloner

# Rules

## Project State

- Treat either root `atlas.config` or `<deps>/atlas.config` as Atlas config. Atlas prefers root
  `atlas.config` when present, but `atlas init` creates `deps/atlas.config` by default.
- Use `atlas init` from the project root to initialize Atlas state.
- Use `atlas init --deps=DIR` or `atlas --deps=DIR init` when the project intentionally uses a
  dependency directory other than `deps/`.
- After initialization, inspect `<deps>/atlas.config`; the default config records `deps`,
  `nameOverrides`, `urlOverrides`, `pkgOverrides`, `plugins`, `resolver`, and `graph`.
- Do not assume `atlas init` creates `nim.cfg`. Atlas has code paths that patch `nim.cfg` when
  dependency operations need compiler paths.

## Commands

- Use `atlas use <url|pkgname>` to add a dependency.
- Use `atlas install` when the Nimble file already contains requirements and Atlas should
  materialize the dependency graph.
- Use `atlas update [filter]` to refresh dependency refs. Prefer a filter when only one dependency
  needs an update.
- Use `atlas link <path>` only for local project linking tasks; be prepared to inspect generated
  link files and the linked project's dependency graph state.
- Use `atlas pin [atlas.lock]` to pin current dependency checkouts.
- Use `atlas rep [atlas.lock]` to replay a lockfile. `atlas replay` and `atlas reproduce` are aliases.
- Use `atlas --noexec rep [atlas.lock]` when replay should avoid build actions that may run
  arbitrary code.
- Use `atlas env <nimversion>` for project-local Nim environments, for example `atlas env 1.6.12`
  or `atlas env devel`.

## Package Names, URLs, And Indexes

- Package names are resolved through Atlas' package lookup table, populated from `packages.json`, plus configured `nameOverrides`.
- URL inputs are parsed as URLs and can be rewritten with `urlOverrides`.
- Forge aliases are valid package references:

| Alias | Expands to |
|-------|------------|
| `gh:user/repo` or `github:user/repo` | `https://github.com/user/repo` |
| `gl:user/repo` or `gitlab:user/repo` | `https://gitlab.com/user/repo` |
| `srht:user/repo` or `sourcehut:user/repo` | `https://git.sr.ht/~user/repo` |
| `cb:user/repo`, `cberg:user/repo`, or `codeberg:user/repo` | `https://codeberg.org/user/repo` |

- Atlas downloads `packages.json` into the package cache by default, using `packages.nim-lang.org`
  with GitHub fallback.
- Use `--packagesRepo` only when the workflow needs the full `nim-lang/packages` git repository behavior.
- Use `--forceGitToHttps` when dependency URLs need `git://` rewritten to `https://`.
- If a package name or URL resolves incorrectly, fix `nameOverrides`, `urlOverrides`, or
  `pkgOverrides` in `<deps>/atlas.config` instead of editing generated paths by hand.

## Generated nim.cfg Paths

- Atlas' `nim.cfg` patcher uses this section shape:

```text
############# begin Atlas config section ##########
--noNimblePath
--path:"deps/pkg"
############# end Atlas config section   ##########
```

- Inspect the Atlas section in `nim.cfg` when imports fail.
- Preserve user-written content outside the Atlas begin/end section.
- Do not hand-edit generated `--path` entries as the first fix. Correct the dependency graph,
  package metadata, or config overrides instead.

## Resolution And Overrides

- Atlas supports `MinVer`, `SemVer`, and `MaxVer` resolver algorithms.
- The generated default config uses `SemVer`.
- Set resolver policy in `<deps>/atlas.config` or with `--resolver=minver|semver|maxver` when the
  task requires a specific policy.
- Use `nameOverrides` for package-name-to-URL mapping.
- Use `urlOverrides` for URL rewrite rules.
- Use `pkgOverrides` when multiple URLs conflict for the same package shortname.
- Keep overrides in Atlas config so future `install`, `use`, `update`, and `rep` commands remain
  repeatable.

## Features

- Atlas supports Nimble `feature` statements.
- Pass feature flags explicitly with `--feature=<feature>`. Pass multiple `--feature` options when
  multiple features are required, or use `--features=<list>` for a comma- or space-separated list.
- Use `--allFeatures` only when every declared feature should be enabled.
- Use `--keepFeatures` or `-k` when the command should reuse feature defines from the current `nim.cfg`.
- Feature request flags populate runtime context; they are not saved as fields in `atlas.config`.
- In Nimble requirements, feature syntax has the shape `require "somelib[testing]"`.

## Plugins And Build Actions

- Atlas plugins are `*.nims` files read from the project-relative directory configured by the `plugins` field.
- Treat plugin execution as potentially arbitrary code execution because plugins can call external tools.
- Inspect the configured plugin directory before enabling plugins or replaying dependencies with execution enabled.
- Use `--noexec` when the task only needs dependency graph setup or lockfile replay and build actions should not run.

## Virtual Nim Environments

- `atlas env <version>` creates a project-local Nim environment under the dependency directory.
- After a successful env setup, activate it explicitly:
  - Unix: `source deps/nim-<version>/activate.sh`
  - Windows: `deps\nim-<version>\activate.bat`
- Do not assume the virtual Nim environment is active in later shell sessions.

# Workflow

1. Inspect the project root.
   Look for `*.nimble`, `nim.cfg`, `atlas.lock`, `deps/`, and any custom dependency directory.
2. Locate Atlas config.
   Check root `atlas.config` first, then `<deps>/atlas.config`; if `--deps` or `--confdir` is in
   use, inspect that configured location.
3. Choose the Atlas command.
   Use `init`, `use`, `install`, `update`, `link`, `pin`, `rep`, or `env` according to the task.
   Run commands from the project root unless `--project=path` is intentional.
4. Check policy before changing dependencies.
   Read resolver, overrides, plugins, feature needs, lockfile state, and existing Nimble requirements.
5. Run the smallest Atlas operation.
   Use filters for targeted updates and `--noexec` when arbitrary build actions should not run.

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template