Workflow guide

Use this guide as your default operating flow in Aisman.

1. Start with project readiness

Before daily work, confirm these project conditions.

1. Project root folder path is set.
2. Root folder exists on the current machine.
3. Required access permissions are granted.
4. .aisman folder is available and writable.

If one of these checks fails, fix it first.

When you switch to another project, Aisman clears the stale workflow state and reloads the session bar and step data for the new project so you do not keep seeing the previous project’s context.

Project-specific UI selections (such as tab/session/story focus) are restored per project after reload, so switching projects does not mix contexts.

When switching projects, the workflow session info bar clears if no valid session exists for the new project. If a session was previously selected in that project, its name is restored. After clicking Review results in Step 4, the session name updates immediately without requiring extra tab switches.

2. Step 1: Select issues

Use this step to prepare only issues that are ready for the next AI pass.

1. Select a session, or start a new one.
2. Review the issue list and expand issues you need to verify.
3. For unfinished items, set a new implementation status and add the required note.
4. Keep only ready issues selected before moving forward.

Helpful behavior in this step:

• Selected issues use visual readiness styles so you can distinguish ready and incomplete items.
• Issue details include notes and status actions directly in the workflow list.
• When you open an issue in the Issues tab and choose Add note, Aisman switches to the Description, Outcome & Notes detail tab automatically so you can start typing immediately.
• Child issues stay grouped under their parent for easier review.
• If an issue is moved from a resolved state back to an unresolved state and it belongs to the current session, it returns to the Step 1 list without forcing a full list rebuild.
• Only the issue list scrolls in Step 1, so the toolbar stays visible while you review longer issue sets.
• When Workflow auto-focuses a tall issue, scrolling favors the top of that issue so the header and action area remain visible.
• When you finish an issue, Workflow can move focus to the next non-ready issue in visual order so you do not need to hunt for the next item manually.
• If selected issues are still incomplete, Aisman blocks the next step and asks you to fix them first.
• The action row supports quick batch operations through Select: controls (Ready, Non-ready, Last step, All) with live counters.
• Last step uses issues from the latest step of the selected session and can be combined with keyboard modifiers.
• Modifier behavior for Select: controls is strict: plain click only changes checkbox state, Shift adds expand behavior, Ctrl deselects, and Ctrl+Shift deselects with collapse.
• In unresolved-only views, issues moved to consolidation are removed from visible unresolved lists immediately.
• Status buttons are hidden while the note editor is open and are restored after Save or Cancel.
• Pressing Escape or clicking Cancel while editing a note always shows a confirmation dialog before discarding your changes — input is never silently lost.
• Long note textareas auto-grow naturally up to 70% of the viewport height, then stop growing and use their own scrollbar. This prevents the issue list from jumping around while you type.
• While a textarea has focus in Step 1, keyboard shortcuts for issue navigation and status changes are temporarily disabled so typing is not interrupted.
• Clicking anywhere inside an issue container applies focused styling to that issue.
• Collapsed selected non-ready items expand first on header click; uncheck behavior is reserved for explicit uncheck interactions.
• If a focused issue is collapsed, status keyboard shortcuts are intentionally blocked until you expand that issue.
• If the latest user note is already the newest note on an issue, status changes can proceed without creating an additional note.
• Mark as done confirmation dialogs show the issue title first so you can verify you are updating the correct issue.
• In Add issues mode, Aisman supports Select all unresolved and Deselect all actions.
• In consolidation sessions, resolved issues are guarded so they cannot be re-added accidentally.
• In add-issues mode, resolved rows are protected from being checked and show a guard message instead.
• Session and step issue rows include type icons for faster visual scanning.
• Show X unassigned can add manually created unassigned issues into Step 1 when they are available and not already being processed elsewhere.
• If some unassigned issues are currently locked by active processing, Aisman shows a warning hint with an explanation icon so the displayed count is clear.
• When you move an issue from session issue views to consolidation and return to AI sessions, Aisman updates only affected rows instead of reloading the whole list.

Auto-focus controls in this step:

• A toolbar near Next step lets you toggle one of three modes: focus latest-step issues, focus non-latest unresolved issues, or full automatic mode.
• Modes are mutually exclusive, and clicking the active mode again turns auto-focus off.
• Latest-step mode can prompt you to continue with other unresolved issues after all latest-step items are reviewed.
• Auto-focus tracks already-focused issues in memory so repeated focus actions skip items already reviewed in the current pass.
• If there are no unresolved last-step issues, Workflow switches auto-focus mode to Auto.

3. Step 2: Instructions

Use this step to prepare and maintain story text.

What you can do here:

• Work with grouped stories, including ungrouped and epic-based groups.
• Toggle additional views such as executed stories and stories of others.
• Use item-height controls to switch between compact and expanded list titles.
• Keep draft safety with local persistence while editing.
• As soon as a detected output file exposes step.storyTitle, Aisman can update the matching story title in the list before the file is fully processed.
• Switching stories keeps unsaved text in local state and local storage so editing context is not lost.
• Use Enter in the story filter to quickly add/select the first matching story.
• Keep using the toolbar around Paste for Preview/Edit and Save/Cancel/Deselect actions.
• See unsaved-change state directly in the stories list using the dirty indicator.
• Stories that are part of an active processing run are preview-only until processing is canceled.
• If you try to switch a processing story into Edit mode, Aisman keeps it locked and explains why instead of allowing edits.
• Executed stories can disappear from the active list immediately when executed filters are off, and an open detail pane is cleared automatically when that happens.
• Each story remembers whether you last used Edit or Preview so returning to it restores the same mode.
• The Load X more control is relevant only when executed stories are currently visible.
• When you deselect a story, Aisman clears the story fields and shows the empty-state prompt instead of leaving the detail panel open.
• When an executed story is selected, you can jump directly to the linked AI session step from the story toolbar.
• Executed stories open in read-only markdown mode and hide edit-save controls.
• Story content is auto-focused after creating a new story.

When the dashboard has enough horizontal space, Aisman can show direct S1, S2, S3, S4 shortcut tabs between Workflow and Settings for faster switching.

4. Step 3: Generate

Use this step to create the prompt payload for your AI coding pass.

1. Confirm selected issues and instructions content.
2. Generate or refresh the output text for the current step.
3. Copy the generated content and send it to your coding agent.

Only ready-selected issues should be included when you generate the final prompt.

If your full generated input is very long, Aisman can copy a compact mandatory header to clipboard when processing starts, while still keeping the complete generated text visible in Step 3.

If needed, use the Step 3 Cancel action to return to Instructions and unlock the currently prepared story.

5. Step 4: Process output

Use this step to monitor and process the produced output file.

1. Wait for the matching output file to be detected.
2. Watch progress as the file is updated.
3. Validate the file when the agent confirms completion.
4. Process automatically or manually based on validation and settings.

In this step, Aisman can show:

• Live progress states from file detection through validation.
• Running/updated file feedback while the agent is still writing.
• Guided actions for errors or warnings (including Fix and re-check flows).
• A direct Get checkin message action that copies the generated message to your clipboard without opening the confirmation dialog first. The message includes correct issue numbers (acronym-number format) for both pre-existing and newly created issues.
• When an output file is processed, any linked user story is immediately marked as executed and locked from further editing or reuse in other steps.
• Multiple concurrent process tabs when more than one workflow run is active.
• Restored in-progress task state after reload when task data is still available.
• Automatic navigation to Step 4 when unfinished processing tasks are restored.
• Immediate tracker close actions for completed or ignored file-processing trackers.
• A OK, close this tracker action that closes the current tracker and jumps to the next useful tracker or back to the last tab you used.
• Unified “user input required” prompts when an output file reaches a stage that needs your decision.
• In-app progress labels that summarize whether the agent is working, finishing, ready for processing, or needs fixes.
• Consistent archive behavior whether processing starts from Project outputs or Workflow Step 4.
• A successful re-check switches back to the normal all-fixed state instead of leaving an empty error list behind.
• If you switch project or reload while processing, Step 4 tracker state can be restored so processing context is not lost.
• After processing completes, processing labels are removed immediately from related list rows so stale Processing... indicators do not linger.
• Step 4 attention badges are shown as soon as a tracker needs your action, including cases where only the processing-check link is visible.
• If you use the processing-check link while a tracker is waiting, Aisman can jump directly to the Fix flow so you can immediately inspect and resolve output-file errors.
• If you cancel processing, Aisman clears processing labels and locks across related lists immediately.
• You cannot cancel story processing from Step 3 if that story is already being processed in Step 4. In that case, cancel from Step 4 instead — Aisman shows a warning toast explaining this.
• Output file validation checks that if the input file specifies a userStoryId, the output file must include the same value. A mismatch is a hard error that must be fixed before processing.

Audible processing signal

When enabled in Settings, Aisman plays an audible signal when output file processing completes or encounters errors:

• The signal can be configured to repeat until you stop it.
• When repeat mode is on, a Stop signal button appears in Step 4.
• Any button click on the Workflow panel also stops the signal automatically.
• The signal settings are AudibleSignalWhenFinished (enable/disable) and AudibleSignalRepeat (repeat until stopped).

Diagnostic link for stuck agents

If the agent appears to be stuck during processing (for example, output file is detected but results are not populated), Step 4 shows a (Has the agent actually finished processing?) link next to the waiting message.

Clicking the link opens a dialog that displays:

• What is missing from the output file (for example missing step.processing.end or unpopulated issue results).
• A Get instructions button that copies a diagnostic message to your clipboard with instructions for the coding agent to fix the situation.

Cancel and Escape confirmation

When editing text in textareas or text fields and pressing Escape or clicking Cancel, Aisman always asks for confirmation before discarding your changes. This prevents accidental data loss.

Documentation-session note:

• During help-source generation, Step 3 shows a progress popup while the file is assembled.
• If you press Cancel in Step 3, Aisman closes that popup immediately and unlocks the workflow so you can continue without reloading.

-If an output file is generated from a story and linked back to sessions, you can navigate between story and session contexts using cross-links in the detail panels.

• When a documentation-session output is processed successfully, the server returns the names of the help source files used. The client automatically moves those files into the corresponding .aisman/help/sessionX/processed/ folder so processed sources are archived.

6. Finish and verify

After processing succeeds:

1. Return to Step 1.
2. Re-check newly affected issues.
3. Confirm readiness for the next loop.

When Step 4 closes a finished tracker and sends you back to Step 1, Aisman can restore the just-finished session and focus the first issue from that latest step so you can verify the result immediately.

For full-text search result lists, repeated searches can reopen and highlight an existing subsection instead of creating a duplicate result group.

If new outputs are detected outside the workflow panel, review them in New detected AI outputs before continuing.

7. Settings and maintenance

The Settings area includes several tabs for managing your Aisman configuration:

• AI tool instructions: Edit and manage the instruction file for your coding agent. The file browser uses the browser’s File System Access API to browse your local project files — it never reads from the server. If your browser does not support this API, Aisman shows an error instead of falling back to server browsing.
• Fixes: A maintenance tab with project-scoped fix actions. The first available fix is Fix note newlines, which corrects escaped newline sequences in issue notes for the current project.

8. Pick the right session type

Workflow behavior also depends on session type.

• Normal sessions: standard implementation loop.
• Documentation sessions: docs update loops.
• Consolidation sessions: move unresolved items from older sessions into a fresh active context.
• Periodic sessions: repeatable cycles with restart behavior.

For full behavior details, see Session types.