Instruction files setup

Use this guide to set up the instruction files that Aisman and your AI tool use together.

Choose one setup model

Use either of these approaches.

Option A: Tool-specific instruction file

1. Open your AI tool instruction file, for example .github/copilot-instructions.md.
2. Ensure it includes the required Aisman header that points to ./.aisman/instructions.md.
3. Save and verify the warning indicator is cleared.

Required header text:

# IMPORTANT PROMPT PARSING INSTRUCTIONS:
 Follow **strictly** the instructions in `./.aisman/instructions.md`.

If the first line already exists but the second line is different, review and update it so both lines match exactly.

This option is best when your team already standardizes on one AI coding tool.

Option B: Custom instruction file

1. Create a custom instruction file in your project root.
2. In General settings, choose Custom instruction file under the default instruction source options.
3. Save settings and verify generation uses the selected file.

This option is best when you need repository-specific instruction workflows.

Keep Aisman instructions in sync

On the Aisman instructions settings page:

• Use Preview mode first when reviewing the local .aisman/instructions.md file.
• Save only when content differs from the stored file.
• Use Cancel to undo edits before saving.
• Re-check required reference text after save.

The template view shows the server-managed version of the same file. Use it when you want to compare the local copy with the latest rendered template.

In the comparison overlay, the three columns are:

• Latest version
• Previous version
• Your local version

Only two columns are compared at a time. Use the top toggles to pick the pair, then use difference navigation to move through detected change blocks.

Automatic local instruction refresh

Aisman can check instruction freshness on reload and periodically (at least daily) using the _AismanInstrLastUpdated marker.

• If server and local versions differ and your local file was not manually edited, Aisman can silently refresh your local file.
• If your local file was manually edited, Aisman keeps your version and shows update indicators in Settings.
• Settings can show an info/to-do style tab with a reminder that newer server instructions are available.

Use Update local version in the Aisman instructions settings area when you want to merge or replace local content intentionally.

Permissions and access

When saving an instruction file:

• Aisman may request directory permission for the folder containing that file.
• Granting access allows direct overwrite without repeating picker prompts.
• Access is stored for future saves.
• If the browser only exposes a folder name at first, use the access flow to grant the app permission for the actual project folder.
• The + Create file action creates the file locally in the project folder instead of downloading it.
• When you create or switch to a project, Aisman can create .aisman/instructions.md automatically from the template if the file is missing.

Verification checklist

Use this checklist before starting AI output generation.

1. .aisman/instructions.md exists in project root.
2. Your selected AI instruction file references .aisman/instructions.md.
3. The file can be saved without repeated path-selection dialogs.
4. Aisman instructions and template views open in the expected default mode.

Output JSON consistency reminders

When your team reviews generated output files, verify two high-impact rules:

• Existing issues must be referenced by positive id; newly created issues must use negative tempNum.
• processing.start should reflect when the request started and should not be rewritten later in follow-up edits.
• Each issue.result should be readable multiline Markdown, not a single long line. Encourage line breaks and short headings when that makes the result easier to scan.
• For documentation sessions, use nested help metadata in output files: step.help.issuesIncluded and step.help.inputFiles.

For free-text requirements, use a two-stage issue-description flow:

1. Create new temp issues from the user’s text before you inspect the codebase.
2. After code review, keep the original user wording in the description and add the technical augmentation below a --- separator.

These checks reduce downstream processing errors and improve traceability in session history.

For direct sessions, keep a matching input markdown file in .aisman/inputs/ so requirements can be restored after session compaction.