npm package: @funsaized/copilot-shakespeare
Description: LLM-powered prompt compiler that transforms raw developer intent into structured, framework-matched prompts for GitHub Copilot Chat
Author: funsaized
Latest version: 1.0.0

# 🐙 copilot-shakespeare

> A lean, LLM-powered prompt compiler that transforms raw developer intent into structured, framework-matched prompts for GitHub Copilot Chat.

[![npm version](https://img.shields.io/badge/version-v1.0.0-blue?style=flat-square)](https://github.com/funsaized/copilot-shakespeare)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=flat-square)](https://nodejs.org/)
[![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-Enabled-brightgreen?style=flat-square&logo=github)](https://github.com/features/copilot)

**`copilot-shakespeare`** takes messy, real-world developer requests and compiles them into precision-tuned Copilot prompts using intent analysis and proven framework templates. Whether you're building a REST API, debugging a null pointer exception, or generating a batch of unit tests, it routes your intent to the right prompt structure automatically.

## ✨ Features

- **🤖 LLM-powered intent analysis** — Classifies your request into one of 5 intent types and selects the optimal prompt framework
- **5 proven Copilot frameworks** — File-Scope, ReAct+Stop, RTF, Few-Shot, Chain-of-Thought — each tuned for a specific task shape
- **Rule-based fallback** — Works even when the Copilot API is unavailable (offline, rate-limited, or no auth)
- **Token efficiency audit** — Strip filler words and reduce token count by 5–15%
- **Interactive mode** — Answer clarifying questions one by one for complex tasks
- **Fully standalone** — No OpenClaw, no external npm dependencies, no framework required
- **GitHub Copilot native** — Uses your existing Copilot subscription; no separate API key needed

## 📋 Table of Contents

- [🚀 Quick Start](#-quick-start)
- [🔧 Prerequisites](#-prerequisites)
- [💡 What It Does](#-what-it-does)
- [🎯 Intent Types & Framework Routing](#-intent-types--framework-routing)
- [📖 The 5 Frameworks](#-the-5-frameworks)
- [🔐 Authentication](#-authentication)
- [⚙️ CLI Reference](#-cli-reference)
- [📁 Project Structure](#-project-structure)
- [🧪 Examples](#-examples)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)

## 🚀 Quick Start

### 1. Install

```bash
npm install @funsaized/copilot-shakespeare
# or with npx (no install needed)
npx @funsaized/copilot-shakespeare --intent "Build a REST API"
```

To develop locally:

```bash
git clone https://github.com/funsaized/copilot-shakespeare.git
cd copilot-shakespeare
```

### 2. Authenticate with GitHub Copilot

```bash
# Option A: Set a GitHub PAT (recommended)
export GH_TOKEN=ghp_your_github_token_here

# Option B: Set a pre-existing Copilot token
export COPILOT_TOKEN=your_copilot_token

# Option C: Interactive auth (first run — opens browser)
# Just run any command; it will prompt you automatically
```

### 3. Run it

```bash
node src/cli.mjs --intent "Build a REST API for managing a patient appointment book"

# Output:
# 🎯 Intent: multi-step → React-Stop · ⚡ Framework: react-stop · 💰 ~220 tokens
# ---
# [compiled prompt]
# ---
```

That's it. No `npm install`, no configuration files, no third-party services.

## 🔧 Prerequisites

| Requirement | Details |
|-------------|---------|
| **Node.js** | v18 or higher |
| **GitHub account** | With an active Copilot subscription (Individual, Pro, Business, or Enterprise) |
| **GitHub token** | A Personal Access Token (PAT) with `read:user` scope |

> **Note:** No npm packages are installed. The entire project is pure ESM using only Node.js built-ins (`fetch`, `fs`, `path`, `crypto`, etc.).

## 💡 What It Does

Most developers describe tasks in natural language — messy, contextual, full of implied constraints. GitHub Copilot works best with precise, structured prompts. `copilot-shakespeare` bridges that gap.

### The compilation pipeline

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   "Fix the null pointer exception in auth service"          │
│                                                             │
│                          │                                   │
│                          ▼                                   │
│   ┌─────────────────────────────────────────────────────┐   │
│   │              INTENT ANALYZER                         │   │
│   │  GitHub Copilot (gpt-4.1) — or rule-based fallback  │   │
│   └─────────────────────────────────────────────────────┘   │
│                          │                                   │
│              intentType: debug                               │
│              framework: chain-of-thought                     │
│              task: "Fix the null pointer exception..."       │
│              constraints: [...]                               │
│              success_criteria: [...]                          │
│                                                             │
│                          ▼                                   │
│   ┌─────────────────────────────────────────────────────┐   │
│   │           FRAMEWORK TEMPLATE                         │   │
│   │  Chain-of-Thought prompt structure applied           │   │
│   └─────────────────────────────────────────────────────┘   │
│                          │                                   │
│                          ▼                                   │
│   ┌─────────────────────────────────────────────────────┐   │
│   │              COMPOSER                                │   │
│   │  Metadata + token estimate attached                  │   │
│   └─────────────────────────────────────────────────────┘   │
│                          │                                   │
│                          ▼                                   │
│                                                             │
│   # Debugging & Analysis — Chain of Thought                  │
│                                                             │
│   ## Role                                                   │
│   You are a senior software engineer debugging...            │
│                                                             │
│   ## Problem / Task                                         │
│   Fix the null pointer exception in auth service             │
│                                                             │
│   ## Reasoning Protocol                                     │
│   1. Observe: state what is known...                       │
│   ...                                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## 🎯 Intent Types & Framework Routing

`copilot-shakespeare` classifies every request into one of five intent types and routes it to the best-matching framework automatically:

| Your request looks like... | Intent Type | Framework | Best for |
|----------------------------|------------|-----------|----------|
| "Update the login function to use async/await" | `code-edit` | File-Scope | Precise edits to a specific file or function |
| "Build a REST API endpoint for user authentication with JWT" | `multi-step` | ReAct+Stop | Multi-file features with checkpointing |
| "How does the JWT refresh flow work?" | `question` | RTF | Quick explanations and how-tos |
| "Write unit tests for all services in this folder" | `pattern` | Few-Shot | Repeated generation from examples |
| "Fix the null pointer exception in auth service" | `debug` | Chain-of-Thought | Debugging and error analysis |

You can override the automatic routing with `--framework`:

```bash
node src/cli.mjs --framework rtf --intent "How does the retry logic work?"
```

## 📖 The 5 Frameworks

### 1. 📄 File-Scope
**For: precise code edits**

Produces a scoped edit prompt with:
- Role definition
- Target file + scope boundary (do-not-touch list)
- Task, constraints, and stop conditions
- Checkpoint format for confirming changes

### 2. 🔄 ReAct + Stop Conditions
**For: multi-step tasks and feature builds**

Produces a step-by-step prompt with:
- End goal stated upfront
- Scope limits as constraints
- Protocol: think → act → checkpoint → continue
- Stop conditions that define "done"

### 3. 🎯 RTF (Role, Task, Format)
**For: quick questions and explanations**

Produces a minimal, focused prompt with:
- Clear role definition
- Specific task statement
- Output format constraint (e.g., "answer concisely with code examples")

### 4. 🪄 Few-Shot
**For: pattern-based generation**

Produces a template-driven prompt with:
- Role + task
- 2–3 input/output examples
- Pattern format constraints
- Consistency rules for naming and style

### 5. 🧠 Chain-of-Thought
**For: debugging and root-cause analysis**

Produces an analytical prompt with:
- Problem statement
- Structured reasoning protocol: observe → hypothesize → investigate → conclude → verify
- Verification checklist from success criteria

## 🔐 Authentication

`copilot-shakespeare` uses GitHub's OAuth2 device flow to obtain a Copilot API token. Tokens expire after ~25 minutes and are automatically refreshed.

### Token resolution order

| Priority | Method | How |
|----------|--------|-----|
| 1 | `COPILOT_TOKEN` env | Pre-existing Copilot token — skips all auth |
| 2 | `GH_TOKEN` / `GITHUB_TOKEN` env | GitHub PAT — auto-exchanged for Copilot token |
| 3 | Disk cache | `~/.config/copilot-shakespeare/token.json` |
| 4 | Interactive device flow | Opens browser for GitHub login (first run only) |

### Getting a GitHub PAT

1. Go to [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
2. Generate new token (classic) with `read:user` scope
3. Add it to your shell profile:

```bash
echo 'export GH_TOKEN=ghp_your_token_here' >> ~/.bashrc
source ~/.bashrc
```

### Rate limits

GitHub Copilot has per-user rate limits. The CLI will wait and retry automatically if you hit a 429. For heavy automation, space requests at least 2–5 seconds apart.

## ⚙️ CLI Reference

### `node src/cli.mjs [options]`

| Option | Alias | Description |
|--------|-------|-------------|
| `--intent <text>` | `-i` | Raw intent text (enclose in quotes) |
| `--file <path>` | `-f` | Path to a `.txt` file containing the intent |
| `--framework <type>` | | Force a specific framework (see below) |
| `--interactive` | | Ask clarifying questions one by one |
| `--audit` | | Run token efficiency audit on the output |
| `--example` | | Show framework routing examples |
| `--help` | `-h` | Show help message |

**Framework values:** `file-scope`, `react-stop`, `rtf`, `few-shot`, `chain-of-thought`

### Examples

```bash
# Basic usage
node src/cli.mjs --intent "Fix the null pointer exception in auth service"

# From a file
node src/cli.mjs --file ./examples/copilot-feature.txt

# Force a specific framework
node src/cli.mjs --framework rtf --intent "Explain the retry logic in 3 sentences"

# Interactive mode for complex tasks
node src/cli.mjs --interactive

# With token audit
node src/cli.mjs --audit --intent "Build a patient appointment rescheduling flow"

# Show routing examples
node src/cli.mjs --example
```

### Output format

```
🎯 Intent: <intentType> → <Framework> · ⚡ Framework: <framework> · 💰 ~<tokens> tokens · 💡 <strategy>

---
[compiled prompt]
---

[optional audit notes]
```

## 📁 Project Structure

```
copilot-shakespeare/
├── README.md                  # This file
├── package.json                # Minimal project metadata
├── examples/
│   └── copilot-feature.txt    # Example intent input
└── src/
    ├── cli.mjs               # CLI entry point + argument parsing
    ├── copilot-llm.mjs       # GitHub Copilot API wrapper (auth + chat)
    ├── analyzer.mjs          # LLM intent extraction + intent-type classification
    ├── frameworks.mjs        # 5 framework template functions
    ├── composer.mjs          # Combines analysis + framework into final prompt
    ├── auditor.mjs           # Token efficiency analysis
    └── fallback.mjs          # Rule-based fallback when Copilot API is unavailable
```

### Key design principles

- **No shared state** — Each invocation is stateless
- **Graceful degradation** — Copilot API unavailable? Falls back to keyword-based rules automatically
- **No lock-in** — Plain text output; review, edit, and paste into Copilot Chat yourself
- **Transparent** — Output shows intent type, framework, token count, and strategy before the prompt

## 🧪 Examples

### Example 1: Multi-step build task

**Input:**
```
Build a patient appointment rescheduling flow.
Stack: React frontend, TypeScript, Node.js API.
Constraints:
- Keep existing OAuth2 login flow unchanged.
- Do not break current appointment booking endpoint.
- Add audit logging for all reschedule actions.
Acceptance Criteria:
- User can select an existing appointment and choose a new time slot.
- API rejects overlapping appointments for same provider.
```

**Output (ReAct+Stop framework):**
```
🎯 Intent: multi-step → React-Stop · ⚡ Framework: react-stop · 💰 ~280 tokens

---
# Multi-Step Implementation (ReAct + Stop Conditions)

## Role
You are a senior software engineer executing a multi-step implementation task.

## End Goal
Build a patient appointment rescheduling flow.

## Context
React frontend, TypeScript, Node.js API.

## Scope Limits (Narrowing)
- Keep existing OAuth2 login flow unchanged.
- Do not break current appointment booking endpoint.
- Add audit logging for all reschedule actions.

## Stop Conditions (Done When ALL Met)
- User can select an existing appointment and choose a new time slot.
- API rejects overlapping appointments for same provider.

## Execution Protocol
1. Think: what is the current state and what is needed next?
2. Act: make one or two related changes in a single pass.
3. Stop: after each step, output a checkpoint...
...
```

### Example 2: Debug task

**Input:**
```
Fix the null pointer exception in auth service
```

**Output (Chain-of-Thought framework):**
```
🎯 Intent: debug → chain-of-thought · ⚡ Framework: chain-of-thought · 💰 ~140 tokens

---
# Debugging & Analysis — Chain of Thought

## Role
You are a senior software engineer debugging or analyzing a problem systematically.

## Problem / Task
Fix the null pointer exception in auth service

## Reasoning Protocol
1. Observe: state what is known from the input/error.
2. Hypothesize: propose the most likely root cause(s).
3. Investigate: walk through how to verify each hypothesis.
4. Conclude: give the likely fix or answer.
5. Verify: describe how to confirm the fix works.
...
```

### Example 3: Token audit

```bash
node src/cli.mjs --audit --intent "Please kindly build a REST API for user authentication"
```

```
Token audit: removed 3 non-load-bearing phrase(s), ~12 tokens saved.
Stripped: please, kindly, Please
```

## 🤝 Contributing

Contributions are welcome! This project is MIT licensed, and all interactive work is public.

### Ways to contribute

- 🐛 **Report bugs** — Open an issue with the input that produced unexpected routing
- 💡 **Suggest frameworks** — Have a prompt framework that works well for a specific task type? Share it.
- 📖 **Improve templates** — The framework templates in `src/frameworks.mjs` are the core asset
- 📚 **Add examples** — Real-world inputs that demonstrate good routing decisions
- ⚡ **Improve fallback rules** — `src/fallback.mjs` can always be more robust

### Development setup

```bash
git clone https://github.com/funsaized/copilot-shakespeare.git
cd copilot-shakespeare

# Test the CLI
node src/cli.mjs --example

# Run with a specific intent
node src/cli.mjs --intent "Add JWT refresh token rotation to the auth endpoint"

# Test the fallback (no auth needed)
node src/cli.mjs --intent "write unit tests for user service"
```

### Commit convention

This project follows [Conventional Commits](https://www.conventionalcommits.org/):

```
feat: add support for custom Copilot API endpoint
fix: improve fallback routing for multi-step detection
docs: add troubleshooting section
refactor: extract token persistence into separate module
test: add routing accuracy tests for each intent type
```

## 📄 License

MIT © 2025 [Sai (funsaized)](https://github.com/funsaized)

## 🙏 Acknowledgments

- The [GitHub Copilot](https://github.com/features/copilot) team for building an exceptional coding assistant
- The community-driven reverse-engineering work on the Copilot API (especially `ericc-ch/copilot-api`, `Alorse/copilot-to-api`, and `copilot-chat.nvim`) that made this integration possible
- [readme-md-generator](https://github.com/kefranabg/readme-md-generator) for README inspiration

---

> **💡 Tip:** For the best results, paste the compiled prompt into Copilot Chat directly — review it first, tweak the constraints if needed, then execute. `copilot-shakespeare` is a compiler; you remain in control of the output.