semester

name	semester
description	Manage semester context. Scaffolds a new SEMESTER.md, updates fields in an existing one, or shows what Pisces currently detects. Use when a student wants to set up or refresh their academic context.

Purpose

The central command for managing semester context — the primary signal Pisces uses to personalize every session. Supports three modes: initialize, update, and status.

Activation

/semester                     # shows status if SEMESTER.md exists, prompts --init if not
/semester --init              # scaffold a new SEMESTER.md interactively
/semester --update            # update fields in the existing SEMESTER.md
/semester --status            # show what Pisces currently detects

---

Mode: --init

Run when no SEMESTER.md exists yet, or when starting a fresh semester.

Step 1 — Collect Details

Ask for all of the following in a single message (do not ask one at a time):

1. Semester and year — e.g., Fall 2025, Spring 2026
2. Current week of semester — integer, e.g., 1
3. Year of study — 1 (freshman) through 6 (graduate)
4. Courses this semester — each as COURSECODE: Course Name, e.g., CS301: Operating Systems. Accept as many as they have. Gently correct codes that don't match [A-Z]{2,4}\d{2,4} (e.g., "cs301" → "CS301").
5. Active project — current assignment or project (or "none")
6. Primary language — language they write most code in this semester
7. Anything they feel weak on — optional

If the student provides some details inline when invoking /semester --init, pre-fill what is already known and only ask for what is missing.

Step 2 — Check for Existing File

Before writing anything, check whether SEMESTER.md already exists in the current directory.

• If it exists: tell the student it was found, show the current content, and ask whether to overwrite it or cancel. Do not proceed unless they confirm.
• If it does not exist: proceed to Step 3.

Step 3 — Write SEMESTER.md

Build the file content with real values — no placeholder text. Use this exact structure:

semester: <semester> <year>
year: <year>
week: <week>
year_of_study: <year_of_study>

## Courses

<one line per course: - COURSECODE: Course Name>

## Active Project

active_project: <project name and course, or "none">

## Current Focus

Working on: <active project or first task>
Upcoming: <first deadline or exam if mentioned, else leave blank>
Feeling weak on: <weak topics, else leave blank>

## Notes

Primary language: <language>

Write this content directly to SEMESTER.md in the current working directory using the file write tool. Do not ask the student to copy-paste it — write the file yourself.

After writing, confirm with: "✅ SEMESTER.md written to <absolute path>."

Tell the student:

• Pisces also searches ~/university/SEMESTER.md — move the file there if you want it to work from any subdirectory
• It is loaded once when Pi starts — restart Pi after moving the file
• Update week: each week and active_project: whenever it changes

Step 4 — Live Preview

Greet the student using their actual semester context to show personalization working immediately.

---

Mode: --update

Run when the student wants to change one or more fields without starting from scratch.

Step 1 — Identify What to Change

Ask: "What would you like to update? (e.g., week number, active project, courses, semester, year of study, weak topics)"

Common update patterns:

• Weekly update — ask for new week: value and new active_project: if changed
• New semester — ask for new semester, year, week (reset to 1), courses, and year_of_study
• Course change — add or remove a course from the list
• Weak topics — replace the "Feeling weak on" line

Step 2 — Write the Updated File

Read the current SEMESTER.md, apply the changes, and write the complete updated file back using the file write tool. Never output a partial file.

Show a brief summary of what changed, then confirm with: "✅ SEMESTER.md updated."

---

Mode: --status

Run to inspect what Pisces currently detects without changing anything.

Output a structured summary of the active session context:

Semester Context
────────────────────────────────────────
Source:          ~/university/SEMESTER.md (or "not found")
Semester:        Fall 2025, Week 7
Year of study:   2nd year
Courses:         CS301, CS315, CS320, MATH210
Active project:  shell-implementation (CS301)
Feeling weak on: Virtual memory, page tables
────────────────────────────────────────
Folder context:  CS301 project detected (cpp, has tests, has CI)

If no SEMESTER.md is found, say so clearly and offer to run --init.

---

Default Behavior (no flag)

• If a SEMESTER.md is detected in the session: behave as --status, then ask if the student wants to --update anything.
• If no SEMESTER.md is detected: explain that it's missing and ask if the student wants to run --init now.

---

Constraints

• Never produce placeholder text in generated file output — use real values from what the student told you, or omit the field if unknown.
• Keep the SEMESTER.md format exactly as shown so the semester-detector extension can parse it correctly.
• Course codes must match [A-Z]{2,4}\d{2,4} — gently correct any that do not.