impl-tool:workflow

impl-tool:workflow@0.0.0

workflowRequest

FieldTypeRequiredDefaultDescription
issuestringYesId of the issue to work, as its queue entry states it; the working branch and the workspace are named from it
issueUuidstringNo""Uuid the queue entry carries for the issue, which the records a run files are attributed to; empty where the entry has none
titlestringYesTitle of the issue, from its queue entry; the session's prompt states it and the pull request opens under it. Empty for a preparation that opens no session
promptstringYesText of the issue from its queue entry, given to the session as its task; empty for a preparation that opens no session
pathpathYesDirectory the run was asked to act on; the checkout the issue is worked in is derived from the repository it belongs to
repoNamestringNoName the remote repository is created under when the directory has no remote, and the name the issue's folder is built from; absent takes the repository's own name
modelstringNoModel the session runs on; absent leaves the choice to the agent
providerstringNo""Agent the session runs on; empty is the default agent
descriptionProviderstringNo""Agent the pull request descriptions are written on; empty is the session's agent
descriptionModelstringNo""Model the description agent runs; empty is that agent's own default
createPullRequestbooleanNofalseWhether pull requests are opened after pushing where none exist yet, for the branch and the submodules it modified; existing pull requests are refreshed either way
headlessbooleanNofalseWhether the session runs as one non-interactive turn instead of an interactive session
continueSessionbooleanNofalseWhether the most recent agent session is continued instead of a new one started
skipSubmodulePullRequestsbooleanNofalseWhether opening pull requests for modified submodules is skipped
pullRequestTemplatePathpathNoPull request template the bodies are written to, in place of the one the config names; a relative path resolves against path
branchstringNoBranch to work and push on, taken literally; absent is impl-tool/<issue>. The workspace is named for the issue either way
basestringNo""Branch pull requests are opened relative to; empty is the checkout's configured default branch. Nothing is reset to it
seedstringNo""Branch whose tip the working branch is reset to before the run; empty resets nothing
skipChecksbooleanNofalseWhether the session is told to skip the verification gate and the tests and to keep its iterations short
skipDescribeOnPushbooleanNofalseWhether the push made after each turn writes no pull request description
releaseStageenum one of dev, prodNo"dev"Stage the work is at, as resolved for the run from --release-stage and the repository's settings; the session's prompt states it
autonomyintegerNo1How much the session decides without asking, from 1 to 5, as resolved for the run from --autonomy and then the config; the session's prompt states what the level means
observebooleanNofalseWhether the main checkout's observer branch is pointed at this issue and kept following it

observerPointing

FieldTypeRequiredDefaultDescription
issuestringYesId of the issue the checkout's observer branch follows
branchstringYesName of the observer branch that follows that issue's work
pointedAtstringNo""Local time the pointing was recorded, as an ISO 8601 timestamp to the second

finishResult

FieldTypeRequiredDefaultDescription
pullRequestUrluriNoLink to the branch's pull request in the repository the call acted on; absent where it has none
createdbooleanNofalseTrue where this call opened that pull request; false where one was already open or none was opened
lineslist[string]No[]The branch as rendered text, one line each: the repository with its pull request and head commit, and beneath it the submodules the branch moved
standinglist[string]No[]One rendered line for each repository whose pull request this call did not simply write to: one already merged or closed and left alone, or one that merged and whose branch has committed since
warningslist[string]No[]What a repository left out of the call still holds that its branch can no longer carry, and a pin still owed where a branch changed nothing but pins, one line each

storedPush

FieldTypeRequiredDefaultDescription
pathstringYesPath of the submodule within the superproject
urlstringYesPush URL the submodule's remote had before the run disabled pushing, which the restore puts back

prepared

FieldTypeRequiredDefaultDescription
workdirpathYesCheckout the issue is worked in: its worktree under the workspaces root, or the directory itself where the work is done in place
branchstringYesBranch checked out there for the run
launchShastringYesCommit the branch stood at once it was prepared, before the session made any
remoteUrlstringYesWhat the checkout's remote is fetched from and pushed to, as git records it and read before pushing was disabled: a url, an address such as git@host:path, or the path of a repository on this machine
storedPushstringYesPush URL the remote had before the run disabled pushing, which the restore puts back
submodulePusheslist[storedPush]No[]Push URL each submodule's remote had before the run disabled pushing, one entry per submodule; empty where pushing was left enabled
sessionCommandcommandYesCommand the agent session is started with
runnerStalestringNo""What a self-update that failed left the run executing: the commit in use against the one its checkout holds. Empty where the update succeeded, was skipped or was not asked for

toolRootState

FieldTypeRequiredDefaultDescription
pathstringNo""Directory of the issue's own tool root; empty where it was not looked for
presentbooleanNofalseWhether that directory exists
orphanedbooleanNofalseTrue where the root exists and the source it was installed from does not, so its executable points at a directory that is gone
notLookedForstringNo""Why the root was not looked for; empty when it was
notOwedstringNo""Why the issue was never given a tool root, where none exists and its repository holds none of impl-tool's source; empty otherwise

issueDirectory

FieldTypeRequiredDefaultDescription
pathstringYesWhere the directory is: inside the issue's folder under the workspaces root, or beside that folder under a name carrying the issue's id
kindenum one of worktree, source, tools, earlierClone, unknownYesWhat the directory is to the issue: worktree where it is edited, source for the tool's exported source, tools for the tool root installed from it, earlierClone for a clone an older layout installed from, and unknown for a directory impl-tool did not make
detailstringNo""What is known beyond the kind: where and at which commit a source was exported, or whether an unknown directory is a checkout. Empty for a worktree and a tool root

sourceExport

FieldTypeRequiredDefaultDescription
checkoutstringYesAbsolute path of the checkout the source was exported from, and is exported from again to bring it up to date
commitstringYesFull sha of the commit the export holds
toolRootstringNo""Tool root installed from this export; empty for the machine's own
fileslist[string]No[]Every file the commit put in the export, as paths relative to it, sorted; the next export removes those its commit no longer tracks

issuePrepared

FieldTypeRequiredDefaultDescription
issuestringNo""Id of the issue prepared for
workdirstringNo""Worktree the issue is edited in
branchstringNo""Branch checked out in that worktree
sourcestringNo""Directory the tool's source is exported into for this issue; empty where the issue has none
toolRootstringNo""Tool root the issue's executable is installed under; empty where the issue has none
executablestringNo""Path of the executable the issue's runs are launched with; empty where none was installed
executableOkbooleanNofalseWhether that executable starts
installedbooleanNofalseTrue where this preparation installed the executable, or reinstalled it
alreadyCurrentbooleanNofalseTrue where a working install was already standing and was left as it was
skippedInstallbooleanNofalseTrue where the preparation was asked to install nothing
noSourcestringNo""Why nothing was exported or installed where no workspacesRoot is configured; empty otherwise
noPackagestringNo""Why the issue gets no executable of its own where its repository holds none of impl-tool's source; empty otherwise
blockedstringNo""Why the install was refused; empty where it was not
blockedByTheCheckoutbooleanNofalseWhich refusal blocked is: true where a trial install made from the source did not start, false where a running process holds the environment
keptUncommittedlist[uncommittedWork]No[]Uncommitted work the worktree already held and the preparation kept because it was asked to, one entry per repository; empty on a clean worktree and on a first preparation
keptNoteslist[string]No[]Issue notes kept as they were edited in the worktree instead of refreshed from the queue; deleting one takes the queue's version at the next preparation

uncommittedWork

FieldTypeRequiredDefaultDescription
scopestringYes. for the top-level repository, otherwise the submodule's path within it
pathslist[string]No[]Changed paths of that repository alone; a submodule's changes are reported under its own scope and never as a path of its parent
behindbooleanNofalseTrue where a submodule's checkout is behind the commit its parent records; kept work is never aligned, so it stays behind until the work is committed or discarded and the preparation is run again

closeResult

FieldTypeRequiredDefaultDescription
statesessionStateNoSession record as it stood when the close began; absent where no session was open
finishfinishResultNo{}What finishing the branch produced: its pull request and tree where the session made changes, and only where the pull requests stand where it made none
callTimingslist[timingEntry]No[]Timing of each model call the close made
modelRunslist[modelRunSummary]No[]Model calls recorded for the repository across every session, summarised per model and priced; rows are ordered as the modelTableSort config key asks
sessionModelRunslist[modelRunSummary]No[]The same summary, restricted to the calls made since this session started
endedbooleanNofalseTrue where the close marked the session as ended; false where an error left it open or no session was open
reachedintegerNo0Highest increment number the branch carries, counted across every session that worked it
incrementsintegerNo0Count of increments made during this session
secondsnumberNo0.0Seconds since the session started; 0 where there is no session or its start time cannot be read
errorstringNo""Why the close-out failed or the model summaries could not be built; empty on success

location

FieldTypeRequiredDefaultDescription
issuestringYesId of the issue the directory asked about is working
workdirpathYesCheckout holding the issue's work; the directory asked about where no other checkout holds it
movedbooleanYesTrue where the work is in a different directory from the one asked about

alignment

FieldTypeRequiredDefaultDescription
alignedlist[string]No[]Paths of the submodules whose clean checkouts were behind the commits recorded for them and were brought to those commits
leftAlonelist[string]No[]Paths of the submodules left where they were because their checkouts hold local changes

derivedMessage

FieldTypeRequiredDefaultDescription
summarystringYesMiddle of the submodule commit's title, without the issue id and the increment number
bodystringYesCommit body with its trailers removed
coauthorslist[string]No[]Co-Authored-By: trailer lines the commit carried
incrementintegerYesIncrement number the commit's title carries

resolvedMessage

FieldTypeRequiredDefaultDescription
summarystringYesMiddle of the commit title the ship uses: the one given, else a moved submodule commit's, else the title of the session's issue
bodystringYesCommit body the ship uses: the one given, else a moved submodule commit's, else the prompt of the session's issue
incrementintegerNoIncrement number given, or the one a moved submodule's commit carries; absent where neither supplied one and the branch's next number is used. Numbering starts at 0
coauthorslist[string]No[]Co-Authored-By: trailer lines of the submodule commit the summary was read off; empty where the summary was given
derivedbooleanNofalseTrue where the summary was read off a moved submodule's commit instead of given

checkout

FieldTypeRequiredDefaultDescription
scopestringYes. for the branch's own repository, otherwise the submodule's path within it
workdirpathYesDirectory of that repository's checkout
repostringNoRepository the checkout pushes to, as owner/name; absent where it has no remote
pullRequeststringYesLink to the repository's pull request for the branch; empty where it has none

pushResult

FieldTypeRequiredDefaultDescription
sectionslist[followUpStateSection]No[]Local follow-up state of each repository the push covered, the branch's own repository first
updatedlist[string]No[]Scopes whose pull request body was rewritten, or would be on a dry run
problemslist[string]No[]What the pre-merge check would refuse about the sections, one line per item, each naming its scope; non-empty means nothing was published
errorstringNo""Why the push stopped or published nothing; empty on success

checkoutWork

FieldTypeRequiredDefaultDescription
pathstringYes. for the checkout the scan was pointed at, otherwise the submodule's path within it
stateenum one of clean, holding, missing, stale, unreadableYesWhat the checkout holds that nothing outside it does: clean for nothing, holding for uncommitted changes or unpushed commits, stale for commits whose patches are all upstream already under other shas, missing for no checkout at the path, and unreadable where git refused
rootstringNo""Tree the row was found in, which tells rows apart when more than one tree is walked
repostringNo""Name of the repository the checkout is of, read from its remote, so every checkout of one repository answers the same; empty where there is no checkout to ask
branchstringNo""Branch the checkout is on; empty where it has no commits yet
uncommittedlist[string]No[]Sample of the changed paths no commit holds, capped; uncommittedCount counts them all
uncommittedCountintegerNo0Count of every uncommitted path found, not only the sample
unpushedlist[string]No[]Sample of the commits reachable from HEAD that no remote holds in any form, each as its short sha, its subject and the refs pointing at it; these are what deleting the checkout would lose
unpushedCountintegerNo0Count of every such commit found, not only the sample
supersededlist[string]No[]Sample of the commits reachable from HEAD that no remote contains but whose patch is already upstream under another sha, as a rebase or a merge leaves them
supersededCountintegerNo0Count of every such duplicate commit found, not only the sample
comparedAgainstlist[string]No[]Remote-tracking refs the commits were compared against for an equivalent patch: the branch's own remote copy and the branch it lands on. Empty means there was nothing to compare against, not that nothing is a duplicate
localOnlylist[string]No[]Sample of the commits no remote holds and HEAD does not reach, held by other local branches; reported and never counted into state, since every checkout of the repository shares them
localOnlyCountintegerNo0Count of every such commit found, not only the sample
localOnlySupersededlist[string]No[]Sample of the localOnly commits whose patch is already upstream, which the refs holding them can be deleted for
localOnlySupersededCountintegerNo0Count of every such commit found, not only the sample
detailstringNo""What needs saying beyond the state: what git refused, why a checkout is missing, or that no remote is configured

scanResult

FieldTypeRequiredDefaultDescription
workdirpathYesCheckout the scan was pointed at; the first tree walked where it walked several
checkoutslist[checkoutWork]No[]One row per checkout walked: each tree's own checkout first, then its submodules
errorstringNo""Why the walk never started or stopped early; empty otherwise

submoduleAlignment

FieldTypeRequiredDefaultDescription
pathstringYesPath of the submodule within the superproject
stateenum one of aligned, moved, ahead, dirty, diverged, missing, sharedYesWhere the checkout stood: aligned already on the branch at its pin, moved taken there, ahead on the branch with commits the superproject has not recorded, dirty left alone over uncommitted changes, diverged where git refused the move, missing where there is no checkout or no pin, and shared where another path already holds the same repository
pinstringNo""Commit the superproject records at this path; empty where it was not read
detailstringNo""Why the submodule was not simply aligned; empty for aligned and moved

syncResult

FieldTypeRequiredDefaultDescription
workdirpathYesSuperproject checkout whose submodules were aligned
branchstringNo""Branch the superproject is on, which every submodule is put on; empty where it could not be read
submoduleslist[submoduleAlignment]No[]One entry per submodule, shallowest first
errorstringNo""Why the alignment never started; empty otherwise

pinMove

FieldTypeRequiredDefaultDescription
pathstringYesPath of the submodule within the superproject
stateenum one of moved, current, unmerged, nested, blocked, missingYesWhat moving the pin came to: moved where it was taken to the merged work and staged, current where it already stood there, unmerged where the pull request has not merged, nested for a submodule of a submodule, blocked where git could not or would not take the checkout there, and missing where there is no checkout
pinnedstringNo""Commit the superproject's HEAD records at this path, read before any move; empty where it was not read
mergedstringNo""Commit the pin moves to or moved to, the tip of the base branch; empty where none was found
pullRequeststringNo""Link to the pull request whose merge the move records; empty where the submodule has none
detailstringNo""Why the pin was not moved; empty for moved and current

pinResult

FieldTypeRequiredDefaultDescription
workdirpathYesSuperproject checkout whose pins were moved
branchstringNo""Branch whose pins were moved; empty where it could not be read
submoduleslist[pinMove]No[]One entry per submodule the branch moved, shallowest first
commitstringNo""Sha of the superproject commit that recorded the moves; empty where none was made, because nothing moved or no commit was asked for
subjectstringNo""Subject of that commit, or of the one that could not be made; empty where none was attempted
errorstringNo""Why the pins were not moved or the moves were not committed; empty otherwise

openResult

FieldTypeRequiredDefaultDescription
branchstringNo""Branch whose pull requests were opened
issuestringNo""Id of the issue the branch works; empty where it could not be told
finishfinishResultNo{}What finishing the branch produced: its pull request, whether this call opened it, and the branch as rendered text
callTimingslist[timingEntry]No[]Timing of each model call made while opening and describing the pull requests
errorstringNo""Why the pull requests could not be opened; empty on success

runReport

FieldTypeRequiredDefaultDescription
exitCodeintegerNo0Exit code of the run: 0 where it completed, 1 where git or the model provider failed
callTimingslist[timingEntry]No[]Timing of each model call the run itself made while wrapping the session up
modelRunslist[modelRunSummary]No[]Model calls recorded for the repository across every session, summarised per model and priced; empty where the run happened inside another session, which reports the record itself
sessionModelRunslist[modelRunSummary]No[]The same summary, restricted to the calls made since this run started
workdirpathNoCheckout the run acted in, which can be another directory than the one it was asked from; absent where the run failed
runnerStalestringNo""What a self-update that failed left the run executing: the commit in use against the one its checkout holds. Empty where the update succeeded, was skipped or was not asked for

shipRequest

FieldTypeRequiredDefaultDescription
pathpathYesDirectory the ship was asked to act on; the checkout holding the issue's work is resolved from it
summarystringNo""What the increment did, as the middle of the commit title; empty takes the summary a moved submodule's commit carries, then the title of the session's issue
bodystringNo""Commit body, wrapped to 72 columns when it is committed; empty takes the body a moved submodule's commit carries, then the prompt of the session's issue
incrementintegerNoIncrement number to commit under; absent takes the number a moved submodule's commit carries, then the next one the branch has not spent
workspacesRootpathNoDirectory the issue's folder is looked for under, as the workspacesRoot config key states it; absent ships from the directory itself
dryRunbooleanNofalseWhether the ship only reports what it would commit and push, changing nothing
pullRequestTemplatePathpathNoPull request template a rewritten body is conformed to; a relative path resolves against the checkout, and absent uses the packaged template

shipCommit

FieldTypeRequiredDefaultDescription
committedlist[string]No[]Paths of the submodules whose uncommitted work this ship committed, deepest first
pushedlist[string]No[]Paths of the submodules whose work was committed already and which this ship pushed
superprojectShastringNo""Sha of the commit made in the top-level repository; empty where none was made
nothingToCommitbooleanNofalseTrue where the tree turned out to hold nothing to commit, so no commit was made
errorstringNo""What stopped the commits partway; committed and pushed still name what went through before it. Empty on success

shipPush

FieldTypeRequiredDefaultDescription
pushedlist[string]No[]Checkouts whose already-committed work was pushed, in the order pushed: submodule paths, then . for the top-level repository
errorstringNo""What stopped the pushing; pushed still names what went out before it. Empty on success

shipRefresh

FieldTypeRequiredDefaultDescription
refreshedlist[string]No[]Repositories whose pull request body was rewritten to match what was pushed: submodule paths, and . for the top-level repository
unopenedlist[string]No[]Repositories whose branch carries commits and has no pull request, named the same way
strandedlist[string]No[]Repositories whose pull request merged while the issue was still being worked and whose branch has committed since, so that work has no pull request; named as submodule paths, and . for the top-level repository

shipFinish

FieldTypeRequiredDefaultDescription
pushshipPushNo{}What pushing the already-committed work reached; empty on a dry run
refreshshipRefreshNo{}Which pull request bodies were rewritten, and which repositories have no pull request to rewrite

shipResult

FieldTypeRequiredDefaultDescription
issuestringNo""Id of the issue the branch works
titlestringNo""Whole title of the commit made: the issue id, the summary and the increment number; empty where no commit was made
incrementintegerNo0Increment number the commit carries, counted from 0; also 0 where no commit was made, which title tells apart
committedlist[string]No[]Paths of the submodules whose uncommitted work this ship committed, deepest first
pushedlist[string]No[]Checkouts whose already-committed work this ship pushed: submodule paths, and . for the top-level repository
superprojectShastringNo""Sha of the commit made in the top-level repository; empty where none was made
messagestringNo""Whole commit message as committed: the title, the wrapped body and the trailers; empty where no commit was made
toolSourcestringNo""Directory holding the issue's exported tool source, which install is pointed at after a ship; empty where the issue has none
toolRootstringNo""Tools directory an install from that source is placed under; empty where the issue has none
nothingToCommitbooleanNofalseTrue where the tree held nothing to commit; work committed already is still pushed
leftUncommittedlist[string]No[]What a ship given no summary found changed and left alone, having no title to commit it under: submodule paths, and . for the top-level repository's own files
refreshedlist[string]No[]Repositories whose pull request body was rewritten to match what was pushed: submodule paths, and . for the top-level repository
unopenedlist[string]No[]Repositories this ship pushed a branch to that still have no pull request, named the same way
strandedlist[string]No[]Repositories whose pull request merged while the issue was still being worked and whose branch has committed since, so that work has no pull request; named as submodule paths, and . for the top-level repository
workdirstringNo""Checkout the ship acted in
movedbooleanNofalseTrue where that is a different directory from the one the ship was asked from
errorstringNo""What stopped the ship; the other fields still report what reached the remotes before it. Empty on success