jackin 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-role 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`.
`jackin role construct-version [<role-repo-path>]`	Prints the construct image version tag pinned in the role Dockerfile. Defaults to the current directory.
`jackin role published-image [<role-repo-path>]`	Prints the published Docker image declared in the role manifest. Defaults to the current directory.
`jackin role published-image-repository [<role-repo-path>]`	Prints the published Docker image repository without its tag or digest. Defaults to the current directory.
`jackin role publish-labels --role-git-sha <sha> [<role-repo-path>]`	Prints the OCI labels required when publishing a role image. Defaults to the current directory.

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-role migrate <role-repo-path>

Publish metadata for CI

The standalone jackin-role binary exposes the role-image metadata that reusable workflows and custom CI need when publishing a role image:

jackin-role published-image-repository .
jackin-role publish-labels --role-git-sha "$(git rev-parse HEAD)" .

published-image-repository prints the published_image repository without a tag or digest. publish-labels prints the canonical Docker label lines, including jackin.construct.version from the role Dockerfile and jackin.role.git.sha from the SHA passed by CI.