🐙 copilot-shakespeare

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

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
• 🔧 Prerequisites
• 💡 What It Does
• 🎯 Intent Types & Framework Routing
• 📖 The 5 Frameworks
• 🔐 Authentication
• ⚙️ CLI Reference
• 📁 Project Structure
• 🧪 Examples
• 🤝 Contributing
• 📄 License

🚀 Quick Start

1. Install

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

To develop locally:

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

2. Authenticate with GitHub Copilot

# 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

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:

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
2. Generate new token (classic) with read:user scope
3. Add it to your shell profile:

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

# 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

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

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:

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)

🙏 Acknowledgments

• The GitHub 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 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.