AIMFP Supportive Context — Core Reference (get_supportive_context tool)

  1. Modular — domain logic in reusable modules
  2. Functional Procedural — pure functions, immutability, no OOP (NON-NEGOTIABLE)
  3. Directive-Driven — workflows loaded from DB, not memory
  4. Database-Driven — DB is source of truth
Four databases: aimfp_core.db (read-only directives/helpers), project.db (files/functions/tasks), user_preferences.db (settings), user_directives.db (Case 2 only).

1. FULL WORKFLOW (directive names in context — use get_directive_by_name() for steps)

  user: "help me create a calculator"

  SESSION START
    1. aimfp_run(is_new_session=true) → full bundle (status, settings, supportive context, watchdog)
       .aimfp-project/ missing → offer aimfp_init or restore from backup
       .aimfp-project/ exists → read status → present next actions
       project_continue_on_start=true → auto-continue; otherwise → await user direction
    2. From bundle: cache project status, settings, supportive context
    3. Need directive details? → get_directive_by_name(name)
    4. Need directive routing? → get_flows_from_directive(name)

  INITIALIZATION (new project only — get_supportive_context(variant='init') for detail)
    5. aimfp_init(project_root) → creates dirs, DBs, blueprint template, .git if missing
    6. AI detects language/tools, prompts user → create_project() → update infrastructure
    7. project_discovery → blueprint, themes, flows, completion path, milestones (NO tasks)
       Pre-existing FP code? → project_catalog first
    8. Routes to aimfp_status → project_progression

  WORK LOOP (project_progression state machine)
    9. get_all_completion_paths → activate first open path
    10. get_milestones_by_completion_path → activate first open milestone
    11. Create ONE task: add_task(milestone_id, name, flow_ids, priority)
        Create items: add_item(reference_table='tasks', reference_id=<task_id>, name, description) or batch via add_items(reference_table='tasks', reference_id=<task_id>, items=[{name, description}, ...])
    12. Work on items (get_supportive_context(variant='coding') for file loop detail):
        a. reserve_file → search_modules for overlap → write FP code → finalize_file
        b. reserve functions → finalize functions (purpose, parameters, returns populated)
        c. add_file_to_flow, add_file_to_module (if domain logic), add_interactions, add_types_functions
        d. Item done → update_item(id=<item_id>, status='completed') or batch via update_items(ids=[...], data={status:'completed'})
    13. All items done → project_task_complete → update_task(status='completed')
    14. More tasks? → create next (goto 11). No → project_milestone_complete
    15. More milestones? → activate next (goto 10). No → project_completion_check → done
        Alternative: update_project_state(project_root, action, target_type, target_id, data)

  MID-WORK CHANGES
    16. Scope/goals change → update blueprint → add_note(note_type='evolution')
    17. Unexpected work → add_sidequest(paused_task_id, flow_ids, name, priority='critical')
    18. Related sub-work → add_subtask(name, parent_task_id, priority='high')

  USER PREFERENCE CHANGES
    19. Directive behavior change → user_preferences_update → add_directive_preference()
    20. Project-wide setting → add_user_setting / update_user_setting → add_note

  SESSION MANAGEMENT
    aimfp_run(is_new_session=false) → watchdog alerts only (at work checkpoints)
    aimfp_status() → fresh state. Call when you can't recall milestone + active task.
    get_supportive_context(variant) → reload reference material on demand.
    Task completion gate: get_task_context(task_id) → verify every finalized file has tracked functions.
    aimfp_end → audit, stop watchdog, log summary.

2. USER REQUEST ROUTING

  Route IN ORDER:
  1. Matches existing task/sidequest/subtask → continue progression
  2. NEW ad-hoc work → project_task_decomposition → create task/sidequest FIRST
  3. Needs a directive workflow → get_directive_by_name(name) FIRST → follow steps
  4. Needs code research → get_file_by_name / get_function_by_name / get_interactions_by_function FIRST
  5. Status/continue/resume → answer from context, call aimfp_status() only if stale

3. AD-HOC WORK & ACCUMULATED CHANGES

  User requests outside current task → project_task_decomposition FIRST.
  Multiple small fixes/requests accumulate into trackable work. After ANY code change:
  did this modify a tracked file? Add a function? Change params/returns/types?
  If YES → AIMFP tracking mandatory immediately. "Small" ≠ "untracked."

4. NOTES REVIEW ON WORK START

  Before beginning any task/sidequest/user request:
    search_notes(search_string=<keywords>, exclude_note_types=['completed','obsolete'])
  Empty = move on. Hits = review for decisions, deferred work, warnings.
  Handled notes → update_note(note_type='completed' or 'obsolete')

5. DIRECTIVE EXECUTION

  ALWAYS load before executing: get_directive_by_name(name).
  Pattern: trunk (main analysis) → branches (conditional) → fallback.
  Deep context: get_directive_content(name). Directive flows ≠ project flows.

6. FP DIRECTIVES & STATE DATABASE

  66 FP directives in 18 categories. Find with get_fp_directive_index() or search_directives(type='fp', keyword='...').
  Key categories: purity, immutability, error_handling, composition, side_effects, anti_oop, type_system, testing.
  State database: auto-created via create_state_database. Replaces mutable globals (set_var, get_var, delete_var, increment_var).

7. GIT & EVOLUTION NOTES

  Branch naming: aimfp-{user}-{number}. Git directives: git_init, git_detect_external_changes, git_create_branch, git_detect_conflicts, git_merge_branch, git_sync_state.
  Any change to blueprint/paths/themes/flows/milestones MUST have add_note(note_type='evolution').

8. EDGE CASES & RECOVERY

  Lost context? aimfp_status() → fresh state. get_supportive_context() → reload reference.
  search_directives(keyword="...") → find the right directive. aimfp_run(is_new_session=true) → full reload.
  Non-FP projects: STOP and REJECT. AIMFP is FP-only.
  DB policy: helpers FIRST → orchestrators → directives → direct SQL (last resort, reads only). Exception: user_directives.db.

9. ADDITIONAL CONTEXT (auto-provided, reload on demand via get_supportive_context(variant=X))

  variant='init'    — auto-provided with aimfp_init() return. Discovery depth, initialization, post-completion paths
  variant='coding'  — auto-provided with aimfp_run(is_new_session=true) for initialized projects. File loop, DRY, interactions, types_functions
  variant='case2'   — auto-provided with aimfp_run(is_new_session=true) when Case 2 active. User directive pipeline, preferences

10. USER SETTINGS

  User preferences system: set_custom_return_statement (attach guidance to any helper — fires on every call), add_directive_preference (key-value prefs loaded with get_directive_by_name), add_user_setting (project-wide config), add_user_directive_note (AI interaction notes in user_directives.db). Use custom return statements for session-boundary behaviors, directive preferences for workflow customization, and user settings for project-wide flags/config.

END SUPPORTIVE CONTEXT
