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.

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.
• 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.
• 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.

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. 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.