role

jackin role is the local role-authoring command family. Use it when you are building or maintaining a role repository from your desktop.

These commands are for desktop/operator workflows. CI, validation workflows, and future Renovate-style migration automation should keep using the small standalone jackin-validate binary so role repositories do not need the full Jackin operator CLI just to validate or migrate their manifest.

Commands

Command	What it does
jackin role validate [<role-repo-path>]	Checks the role manifest, Dockerfile, hooks, environment declarations, and agent table consistency. Defaults to the current directory.
jackin role migrate [<role-repo-path>]	Updates the role manifest to the current schema version, then validates the repository. Defaults to the current directory.
jackin role create <role-name-or-namespace/name> [<projects-dir>]	Creates a starter role repository named jackin-<role-name>. When <projects-dir> is omitted, jackin’ uses JACKIN_PROJECTS_DIR or ~/Projects.

Create a role

Create writes a small valid role repository with a manifest, Dockerfile, README, ignore files, and a GitHub Actions validation workflow:

jackin role create ChainArgos/Backend-Engineer "$HOME/Projects"
cd "$HOME/Projects/chainargos/jackin-backend-engineer"
jackin role validate .

Jackin lowercases the role selector before it creates directories or writes scaffold references. For example, ChainArgos/Backend-Engineer becomes chainargos/backend-engineer, and the repository directory is $HOME/Projects/chainargos/jackin-backend-engineer.

The scaffold is intentionally small. You still own the Dockerfile, manifest, README, and Git history. After reviewing the generated files, initialize the repository and publish it where the selector points:

git init
git branch -M main
git add -A
git commit -m "Initial role setup"
gh repo create chainargos/jackin-backend-engineer --source=. --remote=origin --push

Then load it like any other namespaced role:

jackin load chainargos/backend-engineer . --debug

Validate a role

Validate before pushing role changes:

jackin role validate .

Validation checks the role manifest, Dockerfile, hook paths, environment declarations, and agent table consistency. It uses the same role-repo contract as the standalone validator.

Migrate a manifest

When jackin’ reports that a role manifest needs a newer schema version, run the local migration command from your checkout or pass the role repository path:

jackin role migrate <role-repo-path>

The command rewrites the role manifest in that repository and then validates the result. Inspect the diff, commit it in the role repository, and push it like any other role change.

In CI or automation, use the standalone equivalent instead:

jackin-validate --migrate <role-repo-path>