@shanvit7/poiesis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shanvit7
+
+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,303 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Shanvit7/poiesis/main/apps/web/public/logo.svg" width="72" alt="Poiesis logo" />
+  <h1 align="center">@shanvit7/poiesis</h1>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/@shanvit7/poiesis"><img src="https://img.shields.io/npm/v/@shanvit7/poiesis?color=4f46e5&label=npm&style=flat-square" alt="npm version" /></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@shanvit7/poiesis?color=22c55e&style=flat-square" alt="License: MIT" /></a>
+    <a href="https://github.com/Shanvit7/poiesis/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome" /></a>
+    <a href="https://pi.earendil.works"><img src="https://img.shields.io/badge/pi--package-%E2%9C%93-7c3aed?style=flat-square" alt="pi-package" /></a>
+  </p>
+</p>
+
+A [pi](https://pi.earendil.works) extension that turns any YouTube coding tutorial into a hands-on, test-driven build session.
+
+Pi reads the video, profiles your existing experience, and codes through it chapter by chapter — running every step itself, explaining each decision, and making sure you understand what's being built and why.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Install](#install)
+- [Usage](#usage)
+- [What a session looks like](#what-a-session-looks-like)
+- [Command review](#command-review)
+- [Project structure](#project-structure)
+- [Bundled extensions and skills](#bundled-extensions-and-skills)
+- [Registered tools](#registered-tools)
+- [Prerequisites](#prerequisites)
+- [Local development](#local-development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+
+
+## Features
+
+- **One command** — `/poiesis` does everything: onboard, scaffold, and run chapters
+- **Profile-aware** — scans your GitHub repos to calibrate depth, skips what you already know
+- **Gemini-powered analysis** — feeds the YouTube URL to Gemini, extracts chapters, tech stack, and concepts automatically
+- **Strict TDD flow** — Pi writes the tests; you never write tests. Chapters cannot be marked done until tests are green
+- **Interactive test-plan review** — a full-screen TUI dialog lets you approve, add, or trim checkpoints before a single test is written
+- **Command review gate** — every shell command Pi wants to run is intercepted and shown to you first: run, steer, skip, or ask for an explanation
+- **Theory quizzes** — wrong answers are implemented and run so you see the failure before the fix
+- **Prerequisite gate** — if a chapter's tech is new to you, Pi runs a short primer before the chapter starts
+- **Session-safe** — chapter state persists across context compactions; Pi picks up exactly where it left off
+
+---
+
+
+
+## Install
+
+```bash
+pi install npm:@shanvit7/poiesis
+```
+
+Requires a free Gemini API key — get one at [aistudio.google.com](https://aistudio.google.com/app/apikey):
+
+```bash
+export GEMINI_API_KEY=your-key-here
+```
+
+---
+
+
+
+## Usage
+
+Everything runs through one command:
+
+```bash
+/poiesis
+```
+
+Pi decides what to do based on context:
+
+
+| Situation                         | What happens                                                                       |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| No profile yet                    | Onboarding — pi scans your GitHub and asks a few questions to build your profile   |
+| Profile exists, no active project | Pi asks for a YouTube URL, analyzes the video with Gemini, and scaffolds a project |
+| Inside an active project          | Pi resumes the chapter session from where you left off                             |
+
+
+---
+
+
+
+## What a session looks like
+
+
+
+### Onboarding
+
+Pi scans your GitHub repos (or you describe your projects if preferred) to understand your stack and background. This calibrates every chapter going forward — what to explain, what to skip, and how deep to go.
+
+Profile is saved to `~/.poiesis/user-profile.json`.
+
+### Project setup
+
+Paste a YouTube URL. Pi uses Gemini to analyze the video — chapters, tech stack, concepts, and key takeaways — then scaffolds a project directory:
+
+```
+<project-name>/
+  .poiesis/
+    chapters/
+      .progress.json        ← tracks current chapter and test status
+      chapter-index.md      ← video overview and chapter map
+      chapter-1.md          ← concepts, learning goals, tutor notes
+      chapter-2.md
+      ...
+  .gitignore
+```
+
+
+
+### Chapter session
+
+Each chapter follows a structured flow:
+
+1. **Prerequisite gate** — Pi checks whether the chapter's tech is familiar given your profile. If not, it runs a short quiz and primes you before starting.
+2. **Theory and quiz** — Pi explains the core concepts for this chapter. Wrong answers are implemented and tested so you see the failure before the correction.
+3. **Test plan** — Pi proposes what to verify, shown in a full-screen dialog. You approve or adjust.
+4. **Test file** — Pi writes the test file. You do not write tests.
+5. **Implementation** — Pi codes through the chapter, narrating each decision. You make design calls when asked; Pi handles all shell commands.
+6. **Done** — Tests pass, chapter is marked complete, next chapter queued.
+
+Pi runs all commands. You only answer questions.
+
+---
+
+
+
+## Command review
+
+During an active chapter session, every shell command Pi wants to execute is intercepted and shown to you in a TUI review dialog before it runs:
+
+```
+╔══════════════════════════════════╗
+║  Command Review                  ║
+║                                  ║
+║  npx vitest run tests/ch-1.test  ║
+║                                  ║
+╟──────────────────────────────────╢
+║  > Run it                        ║
+║    Steer                         ║
+║    Skip — don't run this         ║
+║    Explain first                 ║
+╚══════════════════════════════════╝
+```
+
+
+| Choice            | What happens                                                              |
+| ----------------- | ------------------------------------------------------------------------- |
+| **Run it**        | Command executes immediately                                              |
+| **Steer**         | You type a correction (e.g. "use pnpm, not npm") — Pi adjusts and retries |
+| **Skip**          | Command is blocked; Pi continues without running it                       |
+| **Explain first** | Pi explains what the command does and why before re-proposing             |
+
+
+Read-only commands (`cat`, `ls`, `grep`, `find`, etc.) are auto-approved and bypass the dialog.
+
+---
+
+
+
+## Project structure
+
+```
+~/.poiesis/
+  user-profile.json         ← your stack and recent projects (built during onboarding)
+```
+
+```
+<project-name>/
+  .poiesis/
+    chapters/
+      .progress.json
+      chapter-N.md
+```
+
+---
+
+
+
+## Bundled extensions and skills
+
+
+
+### @juicesharp/rpiv-ask-user-question
+
+Registers the `ask_user_question` tool — a structured TUI option selector with typed choices and a free-text fallback. Pi uses this throughout onboarding and chapter sessions wherever a multiple-choice prompt is more precise than a free-form reply.
+
+Source: [npmjs.com/package/@juicesharp/rpiv-ask-user-question](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question)
+
+### agent-browser (skill)
+
+When Pi is unsure about an API, config shape, or error message during your session, it opens the relevant documentation in a headless browser and quotes the live source rather than guessing from training data.
+
+Both are loaded automatically — you don't need to invoke them manually.
+
+---
+
+
+
+## Registered tools
+
+The extension registers the following tools, which Pi calls internally during chapter sessions:
+
+
+| Tool                        | Purpose                                                   |
+| --------------------------- | --------------------------------------------------------- |
+| `poiesis_save_profile`      | Persists the user profile after onboarding                |
+| `poiesis_confirm_test_plan` | Shows the test-plan TUI and captures the student's choice |
+| `poiesis_run_tests`         | Runs the chapter's test suite and records pass/fail       |
+| `poiesis_chapter_done`      | Marks a chapter complete — gated on tests passing         |
+| `poiesis_prereq_done`       | Records the prereq gate result and fires the theory step  |
+| `poiesis_theory_done`       | Fires the test-plan step once theory is understood        |
+| `poiesis_tests_written`     | Records the test file path and fires the implement step   |
+
+
+---
+
+
+
+## Prerequisites
+
+- `[pi](https://pi.earendil.works)` — the coding agent
+- `GEMINI_API_KEY` — free at [aistudio.google.com](https://aistudio.google.com/app/apikey)
+
+---
+
+
+
+## Local development
+
+```bash
+# Install from local path
+pi install /path/to/poiesis/apps/pi-extension
+
+# Test without installing
+pi -e /path/to/poiesis/apps/pi-extension
+
+# Hot-reload after edits (inside pi)
+/reload
+```
+
+---
+
+
+
+## Contributing
+
+Contributions are very welcome — whether it's a bug fix, a new feature, better prompts, or just improving the docs.
+
+### Ways to contribute
+
+- **Bug reports** — open an issue with steps to reproduce and the chapter/step where it broke
+- **Feature ideas** — open a discussion; the best ones get fast-tracked
+- **Code** — fork, branch off `main`, open a PR; see the dev loop above
+- **Prompts** — the `prompts/` directory contains the step prompts Pi uses; improving them has the highest leverage
+- **Eval cases** — `promptfooconfig.yaml` drives the evals; adding cases for tricky scenarios is incredibly valuable
+
+
+
+### Getting started
+
+```bash
+git clone https://github.com/shanvit7/poiesis
+cd poiesis
+pnpm install
+cd apps/pi-extension
+bun install
+```
+
+Run the evals:
+
+```bash
+cd apps/pi-extension
+pnpm eval
+```
+
+
+
+### Guidelines
+
+- The command-review gate must not be bypassable during an active session
+- Prompts live in `prompts/`; logic lives in `src/`; keep them separate
+- Open an issue before a large refactor so we can align first
+
+All contributors are credited in the changelog.
+
+---
+
+
+
+## License
+
+MIT © [shanvit7](https://github.com/shanvit7)
+
+See [LICENSE](./LICENSE) for the full text.