@aethrekh/pi-cs 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to pi-cs (Pisces) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Planned
+- arXiv integration for `/research` skill
+- Model routing presets (local + cloud fallback)
+- Obsidian vault integration
+- `/debug` skill for interactive debugging sessions
+- VS Code extension companion
+
+---
+
+## [0.1.0] — Unreleased (MVP)
+
+### Added
+- Core `system.md` — Pisces academic persona
+- `/homework` skill — Socratic guided learning with integrity guard
+- `/project` skill — Full project kickoff with scaffolding
+- `/review` skill — TA-level code review with severity tiers
+- `/explain` skill — Feynman-style explanations with Mermaid diagrams
+- `/leetcode` skill — Optimized solutions with complexity analysis
+- `/exam` skill — Quiz, mind map, revision plan, and flashcard modes
+- `/research` skill — Paper summarization and literature review
+- `semester-detector` extension — Auto-loads `SEMESTER.md` context
+- `folder-detector` extension — Detects CS university folder structures
+- `integrity-guard` extension — Monitors for academic integrity risks
+- `progress-tracker` extension — Weekly stats and burnout nudges
+- `SEMESTER.md` template for semester initialization
+- Configuration schema with sensible defaults
+- Full TypeScript source with strict mode
+- Jest test suite for all extensions
+- GitHub Actions CI workflow

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Bagdane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# 🐠 pi-cs (Pisces)
+### The CS Student Edition for Pi Coding Agent
+
+> *Your intelligent, adaptive AI co-pilot that swims deep into every aspect of your Computer Science degree.*
+
+**"Your Personal AI Teaching Assistant for Computer Science — From Homework to Thesis"**
+
+---
+
+## What is Pisces?
+
+Pisces is a [Pi Coding Agent](https://github.com/pi-agent/pi) package that transforms Pi into a deeply integrated **academic co-pilot** — the equivalent of a senior TA living inside your terminal.
+
+It covers every dimension of a CS degree:
+
+| Need | Command | What it does |
+|---|---|---|
+| Stuck on an assignment | `/homework` | Hints, pseudocode, guided walkthrough — no cheating |
+| Starting a new project | `/project` | Requirements → architecture → scaffolded codebase |
+| Code review before submitting | `/review` | Strict TA-level review with severity tiers |
+| Don't understand a concept | `/explain` | Feynman-style: analogy + diagram + code example |
+| Interview/LeetCode prep | `/leetcode` | Optimized solutions with complexity proofs |
+| Exam in 3 days | `/exam` | Quiz mode, mind maps, and revision plans |
+| Research paper / thesis | `/research` | Paper summaries, literature surveys, citations |
+
+---
+
+## Quick Start
+
+```bash
+# Install pi-cs
+pi install npm:pi-cs
+
+# Navigate to your university folder
+cd ~/university/fall2025
+
+# Initialize your semester context
+/semester-init
+
+# Start working
+/homework
+/explain binary search trees
+/leetcode 42
+```
+
+---
+
+## Semester Context
+
+Pisces becomes dramatically more useful when it knows your academic context. Create a `SEMESTER.md` in your university root:
+
+```markdown
+semester: Fall 2025
+year: 2025
+week: 7
+year_of_study: 2
+
+## Courses
+- CS301: Operating Systems
+- CS315: Database Systems
+- CS320: Software Engineering
+
+active_project: shell-implementation
+```
+
+Pisces auto-detects this file at startup and greets you with relevant context:
+
+> *"Hey! I see you're in Week 7 of Fall 2025. You have 3 active courses. What are we working on today?"*
+
+---
+
+## Skills Reference
+
+### `/homework`
+Guided learning mode. Pisces uses the Socratic method — hints, pseudocode, and guided questions. **Never produces complete submittable solutions for graded work.**
+
+```
+/homework
+> Here's my problem: implement Dijkstra's algorithm...
+> I've tried a basic BFS but it doesn't handle weights
+```
+
+### `/project`
+Full project kickoff. Requirements analysis, architecture proposal, tech stack recommendation, and scaffolded boilerplate.
+
+```
+/project
+> Build a REST API for a student grade tracker
+> Tech stack: open to suggestions
+> Deadline: 3 weeks
+```
+
+### `/review`
+TA-level code review. Covers correctness, efficiency, style, robustness, and tests. Every issue is rated (🔴 Critical / 🟠 Major / 🟡 Minor / 🔵 Suggestion).
+
+```
+/review --mode=deep
+[paste your code]
+```
+
+### `/explain`
+Feynman-style explanations with real-world analogies, Mermaid diagrams, and connections to your prior knowledge.
+
+```
+/explain virtual memory
+/explain the CAP theorem --depth=advanced
+/explain recursion --style=analogy
+```
+
+### `/leetcode`
+Structured problem solving for interview prep. Full solutions with brute force → optimal progression, complexity proofs, and test cases.
+
+```
+/leetcode 42
+/leetcode trapping rain water --lang=python
+/leetcode --mode=interview    # simulates a real interview
+```
+
+### `/exam`
+Exam preparation toolkit. Interactive quizzes, concept mind maps, day-by-day revision plans, and Anki-compatible flashcards.
+
+```
+/exam CS301 --mode=quiz
+/exam operating systems --mode=mindmap
+/exam --mode=plan          # builds schedule based on your exam date
+```
+
+### `/research`
+Academic research assistant. Paper summaries, literature surveys, citation generation, and literature review writing.
+
+```
+/research "Attention is All You Need"
+/research attention mechanisms --mode=survey
+/research --mode=cite arxiv:1706.03762 --format=bibtex
+```
+
+---
+
+## Academic Integrity
+
+Pisces has academic integrity built in at every level:
+
+- ✅ Always provides hints, explanations, and pseudocode
+- ✅ Helps you debug **your own** code
+- ✅ Writes complete code for personal projects, `/leetcode`, and `/project`
+- ❌ Never writes complete solutions for graded assignments
+- ❌ Never submits or helps disguise AI-generated work as your own
+
+When Pisces detects a potential integrity issue, it redirects to guided learning mode and asks for clarification.
+
+---
+
+## Configuration
+
+Customize Pisces behavior in your Pi config:
+
+```yaml
+# ~/.pi/config.yaml (pi-cs section)
+pi-cs:
+  student:
+    name: Alex
+    year_of_study: 2
+    primary_language: python
+  explanations:
+    default_depth: intermediate
+    prefer_visuals: true
+  productivity:
+    burnout_nudges: true
+    session_warning_minutes: 180
+```
+
+See [`config/schema.json`](config/schema.json) for the full configuration reference.
+
+---
+
+## Installation
+
+**Requirements:** Pi >= 1.0.0, Node.js >= 18
+
+```bash
+pi install npm:pi-cs
+```
+
+That's it. Pisces activates automatically in every Pi session.
+
+---
+
+## Project Structure
+
+```
+pi-cs/
+├── SYSTEM.md                    # Core academic persona (Pi system prompt)
+├── pi-package.yaml              # Package manifest
+├── src/
+│   ├── skills/
+│   │   ├── homework/SKILL.md    # /homework skill
+│   │   ├── project/SKILL.md     # /project skill
+│   │   ├── review/SKILL.md      # /review skill
+│   │   ├── explain/SKILL.md     # /explain skill
+│   │   ├── leetcode/SKILL.md    # /leetcode skill
+│   │   ├── exam/SKILL.md        # /exam skill
+│   │   └── research/SKILL.md    # /research skill
+│   ├── extensions/
+│   │   ├── semester-detector.ts # Auto-loads SEMESTER.md
+│   │   ├── folder-detector.ts   # Detects CS folder structures
+│   │   ├── integrity-guard.ts   # Academic integrity monitoring
+│   │   └── progress-tracker.ts  # Weekly stats & burnout nudges
+│   └── templates/
+│       ├── semester-init.md     # SEMESTER.md template
+│       ├── project-init.md      # CS project bootstrap template
+│       └── research-paper.md    # Academic paper structure template
+├── config/
+│   ├── schema.json              # Config schema
+│   └── defaults.json            # Default values
+└── tests/
+    ├── index.test.ts            # Lifecycle hooks & config tests
+    └── extensions/              # Per-extension unit tests
+```
+
+---
+
+## Roadmap
+
+- [x] 7 core skills
+- [x] 4 background extensions
+- [x] Semester context system
+- [x] Academic integrity guard
+- [ ] arXiv live search integration
+- [ ] Model routing presets
+- [ ] Obsidian vault sync
+- [ ] `/debug` interactive debugging skill
+- [ ] VS Code companion extension
+
+---
+
+## Contributing
+
+Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+For bugs, use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+*Made for CS students, by CS students. 🐠*

package/config/defaults.json

@@ -0,0 +1,25 @@
+{
+  "student": {
+    "year_of_study": 2,
+    "primary_language": "python"
+  },
+  "explanations": {
+    "default_depth": "intermediate",
+    "prefer_visuals": true,
+    "use_analogies": true
+  },
+  "code": {
+    "style": "balanced",
+    "always_include_complexity": true,
+    "always_include_tests": false
+  },
+  "integrity": {
+    "enabled": true,
+    "strictness": "balanced"
+  },
+  "productivity": {
+    "burnout_nudges": true,
+    "session_warning_minutes": 180,
+    "weekly_summary": true
+  }
+}

package/config/schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "pi-cs Configuration",
+  "description": "User configuration for the pi-cs (Pisces) package",
+  "type": "object",
+  "properties": {
+    "student": {
+      "type": "object",
+      "description": "Student profile settings",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Your first name (used for personalized greetings)"
+        },
+        "year_of_study": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 6,
+          "description": "Current year of study (1=freshman, 4=senior, 5-6=graduate)"
+        },
+        "primary_language": {
+          "type": "string",
+          "enum": ["python", "typescript", "javascript", "java", "cpp", "c", "rust", "go", "haskell", "other"],
+          "description": "Your preferred/primary programming language"
+        },
+        "timezone": {
+          "type": "string",
+          "description": "Your timezone (e.g. America/New_York) for deadline awareness"
+        }
+      }
+    },
+    "explanations": {
+      "type": "object",
+      "description": "Settings for the /explain skill",
+      "properties": {
+        "default_depth": {
+          "type": "string",
+          "enum": ["beginner", "intermediate", "advanced"],
+          "default": "intermediate",
+          "description": "Default explanation depth when not specified"
+        },
+        "prefer_visuals": {
+          "type": "boolean",
+          "default": true,
+          "description": "Prefer Mermaid diagrams when explaining structural concepts"
+        },
+        "use_analogies": {
+          "type": "boolean",
+          "default": true,
+          "description": "Include real-world analogies in explanations"
+        }
+      }
+    },
+    "code": {
+      "type": "object",
+      "description": "Code generation preferences",
+      "properties": {
+        "style": {
+          "type": "string",
+          "enum": ["verbose", "balanced", "concise"],
+          "default": "balanced",
+          "description": "How much inline commenting to include in generated code"
+        },
+        "always_include_complexity": {
+          "type": "boolean",
+          "default": true,
+          "description": "Always annotate algorithm time/space complexity"
+        },
+        "always_include_tests": {
+          "type": "boolean",
+          "default": false,
+          "description": "Always suggest test cases alongside solutions"
+        }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "description": "Academic integrity guard settings",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable the academic integrity guard (strongly recommended)"
+        },
+        "strictness": {
+          "type": "string",
+          "enum": ["strict", "balanced", "relaxed"],
+          "default": "balanced",
+          "description": "How aggressively to flag potential integrity issues"
+        }
+      }
+    },
+    "productivity": {
+      "type": "object",
+      "description": "Productivity and wellbeing settings",
+      "properties": {
+        "burnout_nudges": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable rest/break reminders during long sessions"
+        },
+        "session_warning_minutes": {
+          "type": "integer",
+          "default": 180,
+          "minimum": 30,
+          "description": "Show a break reminder after this many minutes in a session"
+        },
+        "weekly_summary": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show a weekly progress summary at session end"
+        }
+      }
+    },
+    "model": {
+      "type": "object",
+      "description": "Model routing preferences",
+      "properties": {
+        "default": {
+          "type": "string",
+          "description": "Default model for general questions"
+        },
+        "code_heavy": {
+          "type": "string",
+          "description": "Model to use for code generation and review tasks"
+        },
+        "quick": {
+          "type": "string",
+          "description": "Lightweight model for fast, simple queries"
+        }
+      }
+    }
+  }
+}

package/extensions/folder-detector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * folder-detector.ts
+ *
+ * Extension: Folder Detector
+ * Triggers: on_startup, on_directory_change
+ *
+ * Detects standard CS university folder structures and injects
+ * project context into the Pi session accordingly.
+ */
+export type ProjectType = "python" | "typescript" | "java" | "cpp" | "rust" | "go" | "web" | "monorepo" | "unknown";
+export interface ProjectContext {
+    type: ProjectType;
+    root: string;
+    name: string;
+    hasTests: boolean;
+    hasCi: boolean;
+    hasDocker: boolean;
+    hasReadme: boolean;
+    entrypoint?: string;
+    testCommand?: string;
+    buildCommand?: string;
+}
+export interface FolderDetectionResult {
+    isUniversityWorkspace: boolean;
+    semesterFolder?: string;
+    courseFolder?: string;
+    project?: ProjectContext;
+}
+export declare function detectFolderContext(): FolderDetectionResult;
+export declare function summarizeFolderContext(result: FolderDetectionResult): string;
+export declare function run(): {
+    inject: string;
+};
+//# sourceMappingURL=folder-detector.d.ts.map

package/extensions/folder-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-detector.d.ts","sourceRoot":"","sources":["../../src/extensions/folder-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,YAAY,GACZ,MAAM,GACN,KAAK,GACL,MAAM,GACN,IAAI,GACJ,KAAK,GACL,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AA+FD,wBAAgB,mBAAmB,IAAI,qBAAqB,CAmC3D;AAID,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAmB5E;AAID,wBAAgB,GAAG,IAAI;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CASxC"}