skillspec act — Expand a decision into an action checklist

skillspec act runs the SkillSpec decision engine on a task, then expands the result into a complete OODA action checklist covering the current execution phase. The checklist includes matched rules, allowed actions, forbidden substitutions, required transitions, phase handoffs, and the effective phase tool boundary — everything an agent needs to choose its next action without guessing. Use act at the start of execution and again before each phase transition. If you need to inspect the phase sequence first without the full checklist, run skillspec plan and then call act --phase <id> for each phase in turn.

Synopsis

skillspec act <path> --input <text> \
  [--trace-dir <dir>] \
  [--run <run-dir>] \
  [--phase <id>] \
  [--json]

--trace-dir and --run are mutually exclusive: use --trace-dir when no trace run exists yet, and --run to associate the checklist with an existing run directory.

Options

Flag	Type	Default	Description
`<path>`	path	(required)	Path to a `skill.spec.yml` file.
`--input`	string	(required)	User task text to route. Strip skill invocation prefixes before passing it. Hyphenated values are accepted.
`--trace-dir`	directory path	(none)	Directory where append-only decision trace event files should be written. Conflicts with `--run`.
`--run`	directory path	(none)	Existing trace run directory to associate with this action checklist instead of writing a new trace. Conflicts with `--trace-dir`.
`--phase`	string	(none)	Expand this execution phase by id instead of the first pending phase. Use after `plan` to target a specific phase.
`--json`	flag	off	Emit JSON instead of a concise human report.

Examples

Basic checklist for the first pending phase:

skillspec act ./skill.spec.yml --input 'port this skill'

Write a new trace and get the checklist in one command:

skillspec act ./skill.spec.yml \
  --input 'port this skill' \
  --trace-dir .skillspec/traces

Associate with an existing run directory (common after run-loop or decide):

skillspec act ./skill.spec.yml \
  --input 'port this skill' \
  --run .skillspec/traces/run-1712345678-12345

Target a specific phase by id:

skillspec act ./skill.spec.yml \
  --input 'port this skill' \
  --run .skillspec/traces/run-1712345678-12345 \
  --phase qa_and_proof

Output

Without --json, act prints a formatted OODA checklist. With --json it emits a structured ActReport:

{
  "input": "port this skill",
  "selected_route": "port_skill",
  "route_selection": {
    "route": "port_skill",
    "basis": "rule_prefer",
    "rule_id": "porting_tasks_use_port_route"
  },
  "matched_rules": [
    { "id": "porting_tasks_use_port_route", "reason": "task matches porting pattern" }
  ],
  "current_phase": {
    "id": "setup",
    "owner_skill": "port-skill",
    "requires": ["validate_source"],
    "checks": ["source_shape_ok"],
    "forbid": [],
    "handoff": null,
    "jumps": [],
    "tool_boundary": null
  },
  "phases": [...],
  "forbidden": ["direct_cli_without_rote_exec"],
  "elicitations": ["approve_scope"],
  "after_success": ["trace_align"],
  "allowed_now": [
    "execute current phase `setup` requirements before later phases",
    "satisfy phase requirements: validate_source"
  ],
  "required_transitions": [
    "complete phase `setup` before starting phase `qa_and_proof`"
  ],
  "before_tool_call": [...],
  "ooda_loop": [...],
  "tool_boundary": {
    "default": "deny",
    "allow": ["skillspec_cli", "current_phase_owner_skill", "..."],
    "forbid": ["direct_cli_without_rote_exec"],
    "permission_required_for": ["any_unlisted_tool", "any_forbidden_action", "..."],
    "instruction": "Use only the allowed tools and substrates for this phase...",
    "sources": ["runtime_default"]
  },
  "authority": "The selected route and matched rules override lower-level skill defaults and generic tool preferences.",
  "trace": {
    "run_id": "run-1712345678-12345",
    "run_dir": ".skillspec/traces/run-1712345678-12345",
    "trace_jsonl": ".skillspec/traces/run-1712345678-12345/trace.jsonl",
    "summary_json": ".skillspec/traces/run-1712345678-12345/summary.json"
  }
}

Field	Description
`current_phase`	The phase being expanded — the first pending phase or the one targeted by `--phase`.
`phases`	Full list of all execution phases in order with their requirements, checks, forbids, handoffs, and jumps.
`forbidden`	Combined forbid set: route-level forbids + current phase forbids + handoff forbids.
`allowed_now`	Concrete list of actions allowed in the current phase.
`required_transitions`	Phase ordering constraints and handoff requirements that must be respected.
`before_tool_call`	Checklist items to verify before every tool call during this phase.
`ooda_loop`	Four-step Observe-Orient-Decide-Act instructions for each iteration.
`tool_boundary`	Effective phase tool boundary merged from `entry.tool_boundary`, route, and phase declarations. `default` is `deny` unless overridden.
`trace`	Paths to the associated trace run when `--trace-dir` or `--run` was supplied.

skillspec plan <path> --input <text> — list phases in order before deciding which one to expand.
skillspec decide <path> --input <text> — raw decision output without the OODA checklist.
skillspec run-loop — batches sensemake, decide, plan, and act in a single spec load.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec act — Expand a decision into an action checklist

Synopsis

Options

Examples

Output

​Synopsis

​Options

​Examples

​Output

​Related

Synopsis

Options

Examples

Output

Related