design-flow

Design Flow

Coordinate module stages, rework and delivery through python3 <skill>/../../framework/scripts/kernel.py, written kernel.py below. <skill> is this skill's directory; {module} contains events.jsonl, intent/brainstorm.md and the stage trees.

The kernel owns events and scheduling. Stage executors own their workdir artifacts and close through the stage CLI, whether running in this conversation or in a subagent. While orchestrating, use the kernel rather than editing events or stage results directly. Inspect source when needed to understand an operation.

Use kernel.py status --module {module} to check current status. Command arguments are available through kernel.py <command> --help.

Run the work

Run the kernel loop:

loop:
  a = kernel.py decide --module {module} [--wake <rule>:<run>] [--closing]
  execute(a)  # actions below; launching a background executor does not wait for it
  if a.action == DONE: finish

For DISPATCH, invoke the returned dispatch_args through the kernel CLI. The response prepares the workdir and identifies the executor; it does not start that executor.

execution	Start the work
main-thread	Invoke the returned skill in this conversation, acting as that stage's executor.
task	Render the stage prompt with the module, rule, skill and workdir from dispatch; launch an independent background executor with that prompt through the host adapter.

Skill names are bare stage names. The host adapter supplies native skill loading and delegation.

After launching a background executor, query decide again so other ready work can proceed. Confirm executor exit through the host before waking or reaping its run; a result file or YIELD does not establish exit. Once it exits, pass --wake <rule>:<run> to decide, including when it left no result. Carry out the returned action:

• REAP: run kernel.py reap --module {module} --rule <rule> --run <run>, then query again. Reap uses that run's result; an absent result is handled as an incomplete execution.
• YIELD: report the running work and wait for an executor completion before resuming.
• ESCALATE: address the reported blocker under the authorization below, then query decide again. Wait when needed information or a reserved human decision is unavailable. kernel.py diagnose records a later addition or correction to repair ownership; --supersedes identifies the diagnosis being replaced.
• DONE: deliver the conclusions and complete any acceptance in scope, as described below.