ShuchangZhang/job-application-tracker

Job Application Tracker

Use a local, portable job board as the single source of truth for application records. Let the user speak naturally; resolve the correct board, preserve existing information, and apply deterministic, conflict-safe changes.

Language Policy

Keep the skill implementation, Agent instructions, references, scripts, schemas, comments, and tests in English. Treat English names and definitions as canonical.

User-facing surfaces may be localized. README.md and the assets/dashboard-* front-end files currently include Chinese and English. Store language-neutral codes for stages and batches so display language never changes the underlying meaning.

Required References

Read only the reference needed for the current operation:

• Read references/data-model.md before recording, updating, validating, summarizing, or reminding.
• Read references/deployment.md before installing, activating, locating, moving, repairing, or starting a board.
• Read references/board-ui.md before rebuilding or changing the dashboard, launchers, local server, or visualization logic.

Resolve the Board First

Denote the selected directory as BOARD_DIR.

Use python3 on macOS/Linux. On Windows, replace python3 in the commands below with py -3 when available, otherwise python.

1. If the user supplies a path, inspect it:

   python3 <skill-dir>/scripts/board_locator.py inspect --board-dir <path>
   

   If it contains valid legacy data.json but lacks the marker, explain that a portable, non-sensitive identity file will be added, then run:

   python3 <skill-dir>/scripts/board_locator.py mark --board-dir <path>
   

2. Otherwise discover marked boards:

   python3 <skill-dir>/scripts/board_locator.py discover
   

3. Interpret discovery exactly:

   • Exit 0: use the single valid board and report its path and record count.
   • Exit 4: ask for an existing path or explicit permission to create a new board.
   • Exit 5: show every candidate and require the user to choose.

Never choose by modification time, record count, or guesswork. Never create a board merely because discovery failed. Never store a global absolute-path registry in the user's home directory.

Safe Data Workflow

For every read or write:

1. Resolve BOARD_DIR.

2. Get the real current date when dates affect the operation: run date +%Y-%m-%d on macOS/Linux or (Get-Date).ToString('yyyy-MM-dd') in Windows PowerShell.

3. Take a snapshot:

   python3 <skill-dir>/scripts/data_store.py snapshot \
     --data <BOARD_DIR/data.json>
   

4. Preserve the returned boardTitle, optional lang, optional stageLevels, all records, all unknown-but-valid record fields, and the returned ETag.

5. For a write, create a candidate JSON file and replace safely:

   python3 <skill-dir>/scripts/data_store.py replace \
     --data <BOARD_DIR/data.json> \
     --input <candidate.json> \
     --expected-etag <etag>
   

6. Treat exit 3 as a concurrent-edit conflict. Take a new snapshot, reapply only the user's requested change, and retry. Never force a stale write.

7. Confirm success only after the tool succeeds.

Never write data.json directly. Never load teaching examples without explicit user confirmation or treat them as real applications. Never modify deployed engine files during a data-only operation.

Core Operations

Record or Update an Application

1. Read references/data-model.md.
2. Match an existing record by company and role. If the target is ambiguous, ask the user to choose.
3. For a new record, require company and role. Ask once for missing optional details—channel, application portal, city, and recruiting batch—then wait for the user's answer or explicit request to skip before saving.
4. Insert a new record at the beginning of records so new applications appear first by default. Preserve the existing array position when updating a record.
5. For an existing record, change only the fields the user mentioned.
6. Advance progress by appending an event; never maintain a separate status field.
7. For an unseen custom stage, preserve its exact text and add a stageLevels rule. Use the user's requested placement; otherwise default to a distinct level immediately before k_hr.
8. Keep note empty unless the user explicitly asks to write something into it.
9. Use the safe data workflow and report the exact record and event changed.

Never fabricate a company, role, date, channel, location, salary, outcome, or interview round.

Show a Text Progress Summary

1. Read references/data-model.md.
2. Take a safe snapshot without modifying data.
3. Put qualifying dated reminders from today through the next seven days first.
4. Group records into in progress, offered, ended, and not yet applied.
5. Identify stale in-progress records and upcoming milestones.
6. End with one concrete next action.

Do not rebuild HTML unless the user explicitly asks.

Open or Rebuild the Visual Board

1. Read references/deployment.md and references/board-ui.md.
2. Resolve and validate the existing board before touching engine files.
3. Normally tell the user to start the board and open http://127.0.0.1:8770/.
4. Recopy the front-end engine set only when an engine file is missing or the user explicitly asks to rebuild or update the engine.
5. Preserve data.json and all backups.

Install or Activate

Read references/deployment.md and follow its discovery-first workflow. Installation of the skill and creation of a new board are separate actions. Creating a board requires explicit user intent.

Hard Rules

1. Use only a resolved, marked BOARD_DIR.
2. Do not silently create a replacement board.
3. Do not recursively scan the user's home directory.
4. Do not store a global path registry.
5. Use data_store.py for every Agent-side data write.
6. Preserve unmentioned data and existing fields.
7. Keep note empty unless explicitly requested.
8. Use neutral stage and batch codes from references/data-model.md.
9. Use the real current date; do not rely on mental date arithmetic.
10. If file-write permission is unavailable, explain the exact manual steps and never claim a write succeeded.
11. Do not combine a data mutation with an engine rebuild unless the user explicitly requests both.
12. Do not overwrite data.json, .data.backup.*.json, or .job-tracker-board.json when deploying or updating engine files.

Bundled Resources

• scripts/board_locator.py: identify, mark, and safely discover board directories.
• scripts/data_store.py: snapshot, validate, conflict-check, atomically replace, and back up data.
• assets/dashboard-template.html, dashboard.css, and dashboard-*.js: localized, dependency-free dashboard modules.
• assets/server.py: loopback-only local server and validated data API.
• assets/start.command / assets/stop.command: macOS launchers.
• assets/start-board.bat / assets/stop-board.bat with matching PowerShell helpers: Windows launchers with health checks and diagnostic logs.
• assets/data.json: empty seed for an explicitly requested new board only.
• tools/: deterministic Sankey crossing-regression utilities.