Shaman Workflow

Use this skill before ship, roast, or land when setup is uncertain. It reads the signs of the current repository; it never repairs anything.

At A Glance

1. Resolve the current repository root and the orchraft plugin root.
2. Run the checks below without changing files, git state, GitHub, or Trello.
3. Report each check as PASS, WARN, or FAIL, then give the smallest next action and an explicit READY or NOT READY result.

Checks

Repository and skill loading

• Confirm git rev-parse --show-toplevel succeeds and report the repository root and current branch.
• Confirm the loaded orchraft package contains skills/ and the skill files named by the requested workflow. If this skill is running, its own loading is a pass; inspect the package for the other requested skills rather than claiming every skill is available.
• Confirm the repository has an origin remote when a GitHub workflow is requested. Do not fetch, push, or alter remotes.

Policy fallback

• For approval-policy.md, config-policy.md, and verification-policy.md, report whether the target repository provides a local copy or orchraft will use the bundled fallback.
• If a local policy exists, read it as the target repository's authority, but verify that context/policies/approval-policy.md matches the freshly resolved default-branch copy before honoring its Autonomous Mode. A missing, unreadable, or mismatched copy cannot pre-authorize actions. A missing local policy is a warning only; fallback is supported.
• When checking Autonomous Mode from the active config, apply the shared config-policy verification rules: compare committed config with the default branch, or require a trusted exact-path ignore source for a local config absent from that branch. Failed or mismatched verification cannot authorize actions.

GitHub access

• If gh exists, run gh auth status and report its result without exposing tokens. A missing or unauthenticated gh is a warning when the configured GitHub connector can provide read access, otherwise a failure for workflows that need GitHub state.
• Confirm the origin URL is a GitHub repository when GitHub work is requested. Do not treat a successful local git command as proof of GitHub authentication.

Required tools

• git is required for every workflow.
• jq is required for the bundled hooks; missing jq is a warning that ambient nudges will be silent.
• gh is required only when no authenticated GitHub connector is available.
• Report missing optional tools plainly instead of inventing a workaround.

Config parsing

• Check .orchraft.jsonc first, then .orchraft.json, and ignore both when neither exists because config is optional.
• Parse the selected file as JSON. For .jsonc, use the same quote-aware comment stripping convention as hooks/watchtower-nudge.sh; never strip // inside a quoted URL.
• A malformed file is a WARN that names the file and parse error, then explain that workflows will continue with documented defaults. Do not edit or rewrite the file.
• For a valid file, check only the documented types that affect the requested workflow. Unknown keys are not failures.

Hook support

• If hooks/hooks.json is present, validate it as JSON, confirm every command it references exists, and confirm referenced scripts are executable.
• Confirm jq is available for the bundled hook scripts.
• Report unsupported host hook behavior as a warning with the host-specific limitation. Never install, enable, or modify a hook.

Output

Use this compact format:

Repository: <root> (<branch>)
<status>  Skills: <result>
<status>  Policies: <local/fallback result>
<status>  GitHub: <authenticated / connector / unavailable>
<status>  Tools: <result>
<status>  Config: <absent / valid path>
<status>  Hooks: <supported / not installed>

Next action: <smallest action, or none>
Result: READY | NOT READY

Use FAIL for a broken prerequisite or malformed config; any FAIL in a requested workflow means NOT READY. Use WARN for a supported fallback or unavailable optional integration; a warning permits READY only when the requested outcome still works through that fallback or the warning concerns an unavailable optional integration. Use PASS only for a check actually performed in this turn. Never claim a check passed from memory.

Guardrails

• Read-only: never create or update a branch, commit, push, fetch, open or update a PR, change an issue or release, mutate Trello, or edit files.
• Do not run commands that write caches, generated files, credentials, or dependency locks.
• Do not print secrets, tokens, full credential paths, or config values that may contain secrets.
• Stop after the report. The shaman may recommend warplan, forgehand, ship, roast, or land, but it never invokes the next workflow.