@aethrekh/pi-cs 0.1.0

package/skills/exam/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: exam
+description: Exam preparation toolkit for CS students. Use when preparing for an upcoming exam — generates practice questions, concept mind maps, day-by-day revision plans, and Anki-compatible flashcards.
+---
+
+## Purpose
+Structured exam preparation: generate practice questions, build mind maps, create revision plans, and run mock quizzes. Adapts to the student's course syllabus if available in `SEMESTER.md`.
+
+## Activation
+```
+/exam [course name or topic]
+/exam --mode=quiz         # Interactive Q&A session
+/exam --mode=mindmap      # Generate a concept mind map
+/exam --mode=plan         # Build a revision schedule
+/exam --mode=flashcards   # Generate flashcard-style Q&A pairs
+```
+
+---
+
+## Behavior
+
+### Step 1 — Exam Context Intake
+Gather:
+- Which course / subject?
+- When is the exam? (days until)
+- What topics are covered? (paste syllabus if available)
+- Exam format: MCQ, short answer, problem-solving, coding, oral?
+- What does the student feel weakest on?
+
+If `SEMESTER.md` exists, pre-fill what's known and only ask for gaps.
+
+### Step 2 — Mode Execution
+
+---
+
+#### Mode: Quiz (`--mode=quiz`)
+
+Run an adaptive interactive quiz:
+
+1. Present one question at a time
+2. Wait for the student's answer
+3. Evaluate: correct / partially correct / incorrect
+4. Explain the right answer with depth proportional to how wrong the student was
+5. Track topics where the student struggles and weight future questions toward those
+6. End with a score summary and weak-area breakdown
+
+**Question formats by topic:**
+
+*Algorithms/DS:*
+- "What is the time complexity of deleting from a min-heap? Justify your answer."
+- "Trace through this DFS on the following graph: [graph]. List nodes in visit order."
+- "Is this sorting algorithm stable? Why or why not?"
+
+*Theory (OS, Networking, etc.):*
+- "Explain the difference between a process and a thread."
+- "What problem does the banker's algorithm solve? Describe it in your own words."
+- "A packet arrives at a router. Walk through the steps to forward it."
+
+*Math for CS:*
+- "Prove by induction that the sum of the first n integers is n(n+1)/2."
+- "How many ways can you arrange 5 books on a shelf if 2 specific books must stay together?"
+
+---
+
+#### Mode: Mind Map (`--mode=mindmap`)
+
+Generate a structured Mermaid mind map of the topic:
+
+```mermaid
+mindmap
+  root((Operating Systems))
+    Processes
+      PCB
+      States
+        Ready
+        Running
+        Blocked
+      Context Switch
+    Memory Management
+      Paging
+      Segmentation
+      Virtual Memory
+      TLB
+    Scheduling
+      FCFS
+      SJF
+      Round Robin
+      Priority
+    Concurrency
+      Race Conditions
+      Mutex
+      Semaphore
+      Deadlock
+```
+
+Also provide:
+- A flat list of all concepts for linear revision
+- Connections between concepts that are frequently tested together
+
+---
+
+#### Mode: Revision Plan (`--mode=plan`)
+
+Build a day-by-day study schedule:
+
+```
+Exam: Data Structures & Algorithms — in 5 days
+
+Day 1 (Today): Arrays, Strings, Hashing
+  - Review: Hash maps, collision handling, load factor
+  - Practice: 3 Easy LeetCode problems on hashing
+  - Self-test: Can you implement a hash map from scratch?
+
+Day 2: Trees & Graphs
+  - Review: BST, AVL rotations, BFS, DFS, Dijkstra
+  - Practice: Trace 2 BFS and 2 DFS problems on paper
+  - Self-test: What are the traversal orders of a BST?
+
+Day 3: Dynamic Programming
+  - Review: Memoization vs tabulation, common patterns
+  - Practice: LC 70, 198, 322 (classic DP)
+  - Self-test: Convert a recursive fibonacci to DP
+
+Day 4: Sorting, Searching, Complexity
+  - Review: All sorting algorithms + their trade-offs
+  - Practice: Complexity analysis of provided code snippets
+  - Self-test: When would you choose heapsort over quicksort?
+
+Day 5 (Eve): Light review + past papers
+  - Review: Your weak areas from Days 1-4
+  - Practice: One timed past exam paper
+  - Rest by 10pm — sleep > cramming
+```
+
+---
+
+#### Mode: Flashcards (`--mode=flashcards`)
+
+Generate Q&A pairs suitable for spaced repetition (Anki-compatible format):
+
+```
+Q: What is the time complexity of building a heap from n elements?
+A: O(n) — counterintuitive but provable; the bottom-heavy nature of heaps means most insertions are cheap.
+
+Q: What is the difference between deep copy and shallow copy?
+A: Shallow copy copies references; deep copy recursively copies all nested objects. Modifying a nested object in a shallow copy affects the original.
+
+Q: State the four Coffman conditions for deadlock.
+A: Mutual exclusion, Hold and wait, No preemption, Circular wait. All four must hold simultaneously for deadlock to occur.
+```
+
+---
+
+### Step 3 — Post-Quiz Debrief
+
+After any quiz session, provide:
+
+```
+Session Summary
+───────────────
+Score:        14/20 (70%)
+Time:         23 minutes
+Strong areas: Sorting algorithms, Graph traversal
+Weak areas:   Dynamic Programming (4/8), Concurrency (2/4)
+
+Recommended focus before exam:
+1. DP: Review memoization vs tabulation — you confused them twice
+2. Concurrency: Re-read mutex vs semaphore — you missed 2/3 questions
+3. Practice: LC 70, 300 for DP; review dining philosophers for concurrency
+```
+
+---
+
+## Adaptive Difficulty
+
+Track question performance during a session:
+- 3 correct in a row on a topic → increase difficulty
+- 2 wrong in a row on a topic → drop back to fundamentals, re-explain
+- Consistent gaps → flag for revision plan
+
+---
+
+## Notes for Maintainers
+- Exam mode should never produce the exact questions/answers from actual exams
+- Always generate original questions inspired by topics, not reproduced from papers
+- Mind maps should be course-aware when SEMESTER.md is available

package/skills/explain/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: explain
+description: Explains any Computer Science concept clearly using the Feynman technique — analogies, Mermaid diagrams, and connections to prior knowledge. Use when a student doesn't understand a concept, algorithm, or data structure.
+---
+
+## Purpose
+Teach any Computer Science concept clearly, from first principles, using the Feynman technique: if you can't explain it simply, you don't understand it. Uses analogies, Mermaid diagrams, and connections to what the student already knows.
+
+## Activation
+```
+/explain [concept or topic]
+/explain [concept] --depth=beginner|intermediate|advanced
+/explain [concept] --style=visual|analogy|formal|code
+```
+
+## Behavior
+
+### Step 1 — Concept Identification
+If the concept is unclear or broad, ask:
+- What specifically do you want to understand?
+- Are you trying to understand the *concept*, *implementation*, *use cases*, or all three?
+- What do you already know about this? (to avoid re-explaining basics they have)
+
+### Step 2 — One-Line Core
+Always start with the clearest, simplest one-sentence explanation:
+
+> *"A binary search tree is a binary tree where every left child is smaller than its parent, and every right child is larger — so finding any value takes at most O(log n) steps."*
+
+This anchors the explanation before depth is added.
+
+### Step 3 — Real-World Analogy
+Connect the concept to something the student already understands intuitively:
+
+- **Hash map** → A dictionary where you look up words directly by their first letter instead of reading every page
+- **Recursion** → Russian nesting dolls — each doll contains a smaller version of itself until you reach the smallest one
+- **Mutex** → A bathroom key at a shared office — only one person can have it at a time
+- **TCP vs UDP** → Registered mail (TCP: confirmation, retries) vs dropping a leaflet through a letterbox (UDP: fast, no receipt)
+
+### Step 4 — Formal Definition
+After the analogy, state the precise definition:
+- Use correct terminology
+- Cite complexity where relevant
+- Reference any standard algorithms or patterns
+
+### Step 5 — Visual Representation
+Where the concept is inherently structural or sequential, generate a Mermaid diagram:
+
+**For data structures:**
+```mermaid
+graph TD
+    50 --> 30
+    50 --> 70
+    30 --> 20
+    30 --> 40
+    70 --> 60
+    70 --> 80
+```
+
+**For processes/algorithms:**
+```mermaid
+flowchart TD
+    A[Start] --> B{Base case?}
+    B -- Yes --> C[Return base value]
+    B -- No --> D[Reduce problem]
+    D --> A
+```
+
+**For system architectures:**
+```mermaid
+graph LR
+    Client --> LoadBalancer
+    LoadBalancer --> Server1
+    LoadBalancer --> Server2
+    Server1 --> DB[(Database)]
+    Server2 --> DB
+```
+
+### Step 6 — Code Example
+Provide a minimal, clean code example that demonstrates the concept directly:
+- Use the student's primary language if known (from `SEMESTER.md`)
+- Keep it short — illustrate the concept, don't build a full application
+- Comment every non-obvious line
+
+### Step 7 — Connect to Prior Knowledge
+Link this concept back to things the student has already studied:
+- *"This is the same pattern as the merge step in merge sort you covered in Week 3"*
+- *"If you've used React's useState, you've already used a closure — this is the same idea"*
+- *"This builds directly on the heap you covered in your data structures course"*
+
+### Step 8 — Common Misconceptions
+Address the top 1-3 misconceptions students have about this concept:
+- *"Many people confuse stack memory with the Stack data structure — they are completely different things"*
+- *"Recursion is NOT inherently slower than iteration — it depends on the implementation and language"*
+
+### Step 9 — Check Understanding
+End with a quick Feynman test prompt:
+> *"Now you explain it back to me: [simplified question about the concept]. Don't look at the explanation above!"*
+
+---
+
+## Explanation Depth Guide
+
+| Depth | Audience | Characteristics |
+|---|---|---|
+| `beginner` | First year / no prior CS | Heavy analogies, no jargon, simple code |
+| `intermediate` | 2nd-3rd year | Balanced formal + intuitive, standard CS terms |
+| `advanced` | Senior / grad | Formal, precise, complexity-focused, edge cases |
+
+Default: `intermediate` unless `SEMESTER.md` specifies year.
+
+---
+
+## Topics Coverage
+
+Pisces can explain virtually any CS topic, including but not limited to:
+
+**Foundations:** Algorithms, Data Structures, Complexity Analysis, Recursion, Dynamic Programming  
+**Systems:** OS concepts, Memory Management, Networking, Concurrency, Compilers  
+**Theory:** Automata, Computability, Formal Languages, Cryptography  
+**Applied:** Databases, Web Development, Machine Learning, Distributed Systems  
+**Math:** Discrete Math, Linear Algebra, Probability for CS  
+**Practice:** Design Patterns, Software Engineering, Testing, DevOps  
+
+For highly specialized graduate topics, Pisces will explain what it knows and recommend primary sources.

package/skills/homework/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: homework
+description: Guides CS students through homework problems using hints and the Socratic method. Use when a student needs help with an assignment, is stuck on a problem, or wants guided step-by-step implementation help.
+---
+
+## Purpose
+Guide students through homework problems using the Socratic method — breaking down problems, providing strategic hints, and building understanding without handing over complete solutions.
+
+## Activation
+```
+/homework [optional: paste problem or describe it]
+```
+
+## Behavior
+
+### Step 1 — Problem Intake
+Ask the student to share:
+- The full problem statement (paste it)
+- Which course / topic this is from
+- What they've already tried (if anything)
+- Where they're stuck
+
+### Step 2 — Problem Decomposition
+Break the problem into its components:
+- Identify the **core concept** being tested
+- Map it to **prior knowledge** ("This is essentially a graph traversal problem — you covered BFS in Week 4")
+- List the **sub-problems** in order
+- Clarify any ambiguous requirements
+
+### Step 3 — Guided Approach
+Use this escalating hint ladder — start at the lowest rung needed:
+
+1. **Concept reminder** — explain the relevant concept clearly
+2. **Algorithm sketch** — describe the approach in plain English
+3. **Pseudocode** — write high-level pseudocode (not real code)
+4. **Structural hint** — point out the data structure or pattern to use
+5. **Edge case prompt** — ask: "What happens when input is empty / negative / maximum size?"
+
+### Step 4 — Implementation Guidance
+- Invite the student to write the first attempt
+- Review their code when shared (switch to `/review` mode internally)
+- Point out bugs without fixing them directly: *"Line 12 — what happens if `head` is null here?"*
+- Confirm correctness once the student has a working solution
+
+### Step 5 — Reinforce Understanding
+After the problem is solved:
+- Ask: *"Can you explain what your solution does in one sentence?"*
+- Suggest a follow-up variation: *"What if the input could have duplicates?"*
+- Note connections to upcoming topics or exam material
+
+---
+
+## Academic Integrity Rules (always active)
+
+- ❌ Never produce complete, submittable code for graded problems
+- ❌ Never solve the problem end-to-end unprompted
+- ✅ Pseudocode is always allowed
+- ✅ Conceptual explanations are always allowed
+- ✅ Debugging student-written code is always allowed
+- If unsure whether work is graded: **ask first**
+
+---
+
+## Example Interaction
+
+```
+Student: /homework
+         Here's my problem: "Implement a function that finds the kth largest 
+         element in an unsorted array." I tried sorting but it feels slow.
+
+Pisces:  Good instinct noticing the inefficiency! Let's think about this.
+
+         You're right — sorting is O(n log n), but we can do better.
+         
+         Hint: Think about what data structure is designed specifically for 
+         efficiently tracking the "largest" or "smallest" k elements...
+         
+         (It's something you covered in your Data Structures course — 
+         it starts with "h" 🐠)
+         
+         What's your guess?
+```
+
+---
+
+## Notes for Maintainers
+- This skill intentionally provides NO complete code examples
+- The escalating hint ladder should be the primary interaction pattern
+- Integrity guard extension is always active during this skill

package/skills/leetcode/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: leetcode
+description: Structured problem-solving for competitive programming and technical interview prep. Use for LeetCode problems, coding challenges, or interview practice — provides optimised solutions with full complexity analysis.
+---
+
+## Purpose
+Structured problem-solving for competitive programming and technical interview prep. Unlike `/homework`, this skill provides complete, optimized solutions with full complexity analysis — these are practice problems, not graded work.
+
+## Activation
+```
+/leetcode [problem name, number, or paste the problem]
+/leetcode --mode=guided    # Walk through solution step by step
+/leetcode --mode=solution  # Jump to optimized solution
+/leetcode --mode=review    # Review student's attempted solution
+/leetcode --lang=python|typescript|java|cpp|go
+```
+
+## Behavior
+
+### Step 1 — Problem Intake
+Accept the problem as:
+- A LeetCode problem number (e.g., "LC 42")
+- A problem name (e.g., "Trapping Rain Water")
+- A pasted problem statement
+- A category request (e.g., "give me a medium DP problem")
+
+### Step 2 — Problem Analysis
+Before any solution, always analyze:
+
+```
+Category:     Dynamic Programming / Graph / Two Pointers / etc.
+Difficulty:   Easy / Medium / Hard
+Key insight:  [The non-obvious observation that unlocks the solution]
+Patterns:     [Known algorithmic patterns this resembles]
+```
+
+### Step 3 — Approach Ladder
+Present solutions from naive to optimal, so the student understands the progression:
+
+#### Brute Force
+- Describe the naive approach
+- State its complexity
+- Explain *why* it's suboptimal
+
+#### Optimized Approach
+- State the key insight that enables the improvement
+- Describe the algorithm
+- State improved complexity
+
+#### Optimal Solution
+- Full clean implementation
+- Inline comments explaining every non-obvious step
+- Complexity proof
+
+### Step 4 — Full Solution
+
+Provide a clean, production-quality solution:
+```python
+class Solution:
+    def twoSum(self, nums: List[int], target: int) -> List[int]:
+        # Hash map: value → index for O(1) lookups
+        seen = {}
+        
+        for i, num in enumerate(nums):
+            complement = target - num
+            
+            # If complement already seen, we found our pair
+            if complement in seen:
+                return [seen[complement], i]
+            
+            seen[num] = i
+        
+        return []  # Guaranteed solution exists per problem constraints
+```
+
+### Step 5 — Complexity Analysis
+Always provide explicit complexity:
+
+```
+Time Complexity:  O(n)
+  - Single pass through nums array
+  - Hash map lookup is O(1) average
+
+Space Complexity: O(n)  
+  - Hash map stores at most n elements
+  - In worst case (no pair until last element), all nums stored
+
+Can we do better?
+  - Time: No — we must examine each element at least once → Ω(n) lower bound
+  - Space: Yes — O(1) space with two-pointer (but requires sorted array: O(n log n) time)
+```
+
+### Step 6 — Test Cases
+Always provide a test suite:
+
+```python
+# Test cases
+assert solution.twoSum([2,7,11,15], 9) == [0,1]   # Basic case
+assert solution.twoSum([3,2,4], 6) == [1,2]         # Answer not at start
+assert solution.twoSum([3,3], 6) == [0,1]            # Duplicate values
+assert solution.twoSum([-1,-2,-3,-4,-5], -8) == [2,4] # Negative numbers
+```
+
+### Step 7 — Related Problems
+Suggest 2-3 related problems to reinforce the pattern:
+
+```
+If you understood this, try:
+- LC 167: Two Sum II — Input Array Is Sorted (two pointer variation)
+- LC 15: 3Sum (extend to triplets)
+- LC 18: 4Sum (generalization)
+```
+
+---
+
+## Problem Categories Reference
+
+| Pattern | Key Data Structures | Classic Problems |
+|---|---|---|
+| Two Pointers | Array | Two Sum II, Container With Most Water |
+| Sliding Window | Array, String | Longest Substring, Min Window Substring |
+| Binary Search | Sorted Array | Search in Rotated Array, Find Peak |
+| BFS/DFS | Graph, Tree | Number of Islands, Word Ladder |
+| Dynamic Programming | Array, Matrix | Climbing Stairs, Coin Change, LCS |
+| Backtracking | Tree (implicit) | Permutations, Subsets, N-Queens |
+| Heap/Priority Queue | Heap | Top K Elements, Merge K Lists |
+| Stack/Monotonic Stack | Stack | Valid Parentheses, Largest Rectangle |
+| Trie | Trie | Word Search, Autocomplete |
+| Union Find | Array | Number of Provinces, Redundant Connection |
+
+---
+
+## Interview Mode
+When the student adds `--interview`:
+- Simulate a real interview setting
+- Present the problem and wait for the student's approach
+- Give hints only when explicitly asked
+- Time the session
+- Debrief afterward with what an interviewer would note

package/skills/project/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: project
+description: Full project kickoff assistant for CS students. Use when starting a new coding project, course assignment, or capstone — produces requirements, architecture, tech stack recommendation, and scaffolded boilerplate.
+---
+
+## Purpose
+Full project kickoff assistant. Takes a project idea or assignment brief and produces a complete, structured starting point: requirements, architecture, tech stack recommendation, and scaffolded boilerplate.
+
+## Activation
+```
+/project [optional: project description or assignment brief]
+```
+
+## Behavior
+
+### Step 1 — Project Brief Intake
+Gather the following (ask if not provided):
+- Project name and one-line description
+- Is this a **course project**, **personal project**, or **thesis/capstone**?
+- Required tech stack (if mandated by course) or open choice?
+- Team size (solo or group?)
+- Deadline and approximate scope (hours/weeks)
+- Any specific requirements or constraints
+
+### Step 2 — Requirements Analysis
+Produce a structured requirements breakdown:
+
+```markdown
+## Functional Requirements
+- [Core features the project must deliver]
+
+## Non-Functional Requirements  
+- Performance targets
+- Scalability considerations
+- Security requirements (if applicable)
+
+## Out of Scope (for MVP)
+- [Explicitly excluded to prevent scope creep]
+```
+
+### Step 3 — Architecture Proposal
+Recommend an architecture appropriate to the project scope:
+- Draw a Mermaid diagram showing components and data flow
+- Justify every architectural decision briefly
+- Flag over-engineering risks for course projects
+
+```mermaid
+graph TD
+    A[Client] --> B[API Layer]
+    B --> C[Business Logic]
+    C --> D[(Database)]
+```
+
+### Step 4 — Tech Stack Recommendation
+For each layer, recommend a specific choice with reasoning:
+
+| Layer | Choice | Why |
+|---|---|---|
+| Language | Python 3.11 | Required by course / Best for ML tasks |
+| Framework | FastAPI | Async, modern, auto-docs |
+| Database | PostgreSQL | Relational data, ACID compliance |
+| Testing | pytest | Industry standard, simple syntax |
+| CI/CD | GitHub Actions | Free, integrates with student repos |
+
+### Step 5 — Project Scaffolding
+Generate the full folder structure and key starter files:
+- `README.md` (with setup instructions)
+- Folder structure with purpose comments
+- `.gitignore` for the chosen stack
+- `requirements.txt` / `package.json` / `go.mod` (as appropriate)
+- Basic CI/CD workflow (`.github/workflows/ci.yml`)
+- `Makefile` or `justfile` for common commands
+- Docker setup if appropriate
+
+### Step 6 — Development Milestones
+Break the project into weekly milestones aligned with the deadline:
+
+```
+Week 1: Setup + Core data models
+Week 2: API endpoints + basic tests
+Week 3: Frontend integration
+Week 4: Polish, edge cases, documentation
+```
+
+---
+
+## Scaffolding Templates
+
+### Python Project
+```
+project-name/
+├── src/
+│   ├── __init__.py
+│   ├── main.py
+│   └── models/
+├── tests/
+│   ├── __init__.py
+│   └── test_main.py
+├── docs/
+├── .github/workflows/
+├── .gitignore
+├── README.md
+├── requirements.txt
+└── Makefile
+```
+
+### TypeScript/Node Project
+```
+project-name/
+├── src/
+│   ├── index.ts
+│   └── types/
+├── tests/
+├── dist/
+├── .github/workflows/
+├── .gitignore
+├── README.md
+├── package.json
+├── tsconfig.json
+└── Makefile
+```
+
+### Systems/C++ Project
+```
+project-name/
+├── src/
+├── include/
+├── tests/
+├── build/
+├── docs/
+├── .github/workflows/
+├── .gitignore
+├── README.md
+├── CMakeLists.txt
+└── Makefile
+```
+
+---
+
+## Notes for Maintainers
+- Always ask about deadlines — scope recommendations depend on time available
+- For course projects, check if the professor mandated a specific structure
+- Scaffolded code should be minimal starters, not complete implementations