Sharpie Reimagined PRD

One-Sentence Product

Sharpie is a macOS AI rewrite layer for serious work: select a rough thought, press Command-/, and Sharpie sends it through the fastest available user-owned AI path with the right tiny context pack, producing one excellent prompt or task brief.

Why This Exists

Vikky works across many projects, ideas, repos, AI tools, and half-formed thoughts. The expensive part is not typing. The expensive part is reloading context, deciding what the AI needs to know, and turning a lazy impulse into a prompt that gets useful work done.

Sharpie should remove that tax.

The old product was "type a lazy prompt into a small window and get a better prompt on the clipboard." That is useful, but still asks the user to leave flow and wait on a model every time.

The reimagined product is stronger:

Select bad text. Press Command-/. A better task appears where the work already is, or lands on the clipboard when replacement is unsafe.

The window remains, but it is no longer the center of the product. The center is the keystroke.

Target User

Sharpie is built first for Vikky.

That means a developer, product thinker, and AI-heavy builder who:

lives in Codex, Claude Code, Cursor, ChatGPT, Gemini, terminals, browsers, and notes
jumps between many projects and ideas
thinks fast and writes rough first drafts
wants AI agents to do serious work without wasting a turn on missing context
values local-first privacy and hates setup friction
notices when software feels slow, noisy, or overdesigned

If this works for Vikky daily, it will work for other builders like him.

Product Bet

The bet is that the next great AI productivity layer is not another agent. It is a fast, provider-flexible rewrite layer that sits above all agents and translates human intent into excellent instructions.

Sharpie wins if it becomes muscle memory.

Not "I should open Sharpie."

"I wrote something rough. Hit Command-/."

Core Principles

Stay In Flow

Sharpie should operate on selected text in the frontmost app whenever possible. The user should not have to switch apps, copy text manually, paste into Sharpie, then paste back.

Fallback order:

Rewrite selected text in place when safe.
Copy rewritten text to clipboard when replacement is unsafe.
Open the Sharpie window when there is no selected text.

Fast AI Rewrite Is The Feature

Sharpie cannot feel magical if every invocation waits for context discovery plus a cold CLI model call.

The system must make real AI calls feel fast:

Build a Context Pack from cached local snapshots.
Shape and budget the backend prompt locally.
Route to the fastest healthy AI backend the user owns.
Stream or display the rewrite as soon as the backend supports it.
Retry or fail over quickly when a backend is unavailable.

Local logic may classify intent, assemble context, and choose a prompt contract. It must not generate template-like final rewrites. The final output should come from an AI backend unless the user explicitly chooses a non-AI fallback in the future.

One Output, Never A Conversation

Sharpie produces exactly one rewritten prompt or task brief per invocation. It never asks clarifying questions.

If context is missing, the output should include an investigation step, scoped assumption, or explicit instruction to inspect before editing.

Bad:

Which login bug are you referring to?

Good:

Investigate the reported login bug. If multiple login flows exist, identify them first and focus on the one used by the current app entry point.

Context Is A Small Pack, Not A Database

Sharpie should not index the user's computer. It should attach the smallest useful set of local facts for the current rewrite.

A good Context Pack might include:

Frontmost app: Cursor
Project: Sharpie
Git branch: codex/context-pack
Selected text: "fix settings weirdness"
Changed files: Sources/Sharpie/Views/SettingsView.swift, Sources/Sharpie/AppPreferences.swift
Project rules: AGENTS.md summary
Clipboard: recent auth error

That is enough to produce a much better prompt without becoming a surveillance product.

Project Memory Has Two Tiers

Project memory must separate human-authored truth from generated cache.

Human-authored memory lives in the project:

project/
  .sharpie/
    context.md
    preferences.md
    recent-decisions.md
    ignore

Generated indexes and repo-map cache live outside the project:

~/Library/Application Support/Sharpie/Projects/<project-hash>/
  manifest.json
  symbols.db
  files.db
  graph.json
  last-indexed.json

The .sharpie/ folder should be inspectable, editable, and optionally committed. Generated cache should be rebuildable, local-only, clearable, and never committed by default.

Project onboarding should be optional. Sharpie must stay useful without onboarding; onboarding only improves context quality for projects the user explicitly selects.

The Prompt Is The Product

Sharpie's system prompt, context compiler, and backend routing define the experience. The app delivers the prompt, but the rewrite quality is why the product exists.

Prompt changes, context selection changes, and backend routing changes should be reviewed like source code and evaluated against real lazy inputs.

Local Trust

By default, Sharpie itself makes zero outbound network calls. Model traffic happens inside the user's already-installed and already-authenticated CLI backend.

Optional BYOK mode may make direct provider API calls only after the user explicitly enables it. No accounts. No cloud sync. No telemetry. No required API keys. No API-key wall on first run.

Experience Direction

Sharpie should feel like a premium native Mac command instrument: Perplexity's calm and restraint, Spotlight's speed, Raycast's utility, and Apple's quiet confidence.

The visual direction is quiet intelligence:

one luminous intent field
compact Context Receipt
polished task brief surface
warm neutral macOS material
subtle shadow and hairline separators
restrained accent color used only for focus, progress, and success
no dashboard
no sidebar
no chat transcript
no decorative AI flourishes

Command Bloom

The primary interface is a small floating panel that appears immediately on Command-/.

It starts compact:

Sharpie

What are you trying to do?
fix settings weirdness

Cursor · Sharpie · main · 4 files

It expands only when output exists. The window should feel like it is listening, not presenting.

Context Receipt

The Context Receipt is the most important trust detail.

Collapsed:

Cursor · Sharpie · main · 4 changed files · clipboard error

Expanded:

Using
Selected text: "fix settings weirdness"
Project: Sharpie
Branch: main
Changed: SettingsView.swift, AppPreferences.swift
Clipboard: auth error from 2 min ago

The user should always be able to understand what Sharpie used without managing it.

Task Brief Surface

Output should not look like chat. It should look like a clean work order:

Investigate and fix the settings behavior in this macOS SwiftUI app.

Start by inspecting SettingsView, AppPreferences, and any persistence code for backend, hotkey, history, and launch-at-login settings. Identify the exact mismatch between UI state and stored preferences before editing.

Keep the fix narrowly scoped, preserve the existing settings surface, and add focused test coverage if the repo has a preference test pattern.

Report the root cause, files changed, and verification steps.

Actions:

Replace Selection   Copy   Retry   Original

The primary action depends on context. If selected text can be replaced safely, Replace Selection is primary. Otherwise Copy is primary.

Motion

Motion should make the app feel responsive, not animated for its own sake.

hotkey opens the panel within 100ms
panel fades and scales from 98% to 100%
context row appears immediately after capture
output expands the panel vertically
copied toast moves only a few pixels
reduced motion disables flourish

No bounce. No elastic easing. No dramatic reveal.

User Experience

Primary Flow: Selection Rewrite

User writes or sees rough text in any app.
User selects the text.
User presses Command-/.
Sharpie shows the HUD or Command Bloom immediately.
Sharpie builds a Context Pack from cached snapshots.
Sharpie assembles a compact backend prompt.
Sharpie routes to the fastest healthy AI backend.
Sharpie replaces the selected text if safe.
If replacement is unavailable, Sharpie copies the result and shows "Copied."

Target feeling: instant command-space utility.

Fallback Flow: Sharpie Window

User presses Command-/ with no selected text.
Sharpie opens a centered floating window.
The input is focused, optionally prefilled from the clipboard if useful.
User types rough intent and presses Return.
Sharpie generates one output through the same AI rewrite pipeline.
Sharpie copies it.
Pressing Return again dismisses.

The window is for composition, not conversation.

Recovery Flow

Command-Z restores the original input after a rewrite.
Esc dismisses without losing clipboard state.
Errors keep the original text available.
If a backend fails, Sharpie quickly tries the next healthy configured backend when available.
If no backend succeeds, Sharpie keeps the original input and explains the likely fix in one line.

Example:

Claude Code did not respond in time. Try Codex, Gemini, or enable BYOK Fast Lane.

Output Shapes

Sharpie should infer intent invisibly and choose the right output shape. The user should not choose modes from a picker.

Build

For feature or implementation requests.

Implement ...

Start by inspecting ...
Keep the change scoped to ...
Preserve ...
Add or update tests for ...
Report ...

Debug

For bugs, errors, logs, and broken behavior.

Investigate and fix ...

First reproduce or trace ...
Identify the root cause before editing ...
Check ...
Add a regression test if ...
Report root cause, fix, and verification.

Review

For "is this good", code review, design review, PR review, and critique.

Review ...

Prioritize correctness, regressions, missing tests, and user-facing risks.
Lead with findings, ordered by severity.
Include file/line references when available.
Do not rewrite unless a fix is clearly needed.

Plan

For product, architecture, or execution planning.

Create a concise plan for ...

Name the goal, constraints, tradeoffs, likely risks, and first implementation slice.
Call out decisions that need explicit approval.
Keep the plan biased toward shipping.

Pitch

For messages, README copy, launch notes, PRDs, and narrative artifacts.

Rewrite this into ...

Make the audience, value, and next action obvious.
Preserve the user's intent and voice.
Remove filler.

Fast Rewrite System Design

Latency Budgets

These are product requirements, not nice-to-haves.

Step	Target
Hotkey to visible UI	under 100ms
Selected text capture or fallback decision	under 250ms
Context Pack build from cache	under 50ms
Prompt assembly and budgeting	under 80ms
Dispatch to selected backend	under 500ms
CLI rewrite, p50	under 3s
BYOK Fast Lane rewrite, p50	under 2s
Backend hard timeout	8s

If a step misses budget, Sharpie should degrade to the next fastest useful path instead of waiting.

Speed Ladder

Sharpie uses the fastest path that can produce a good output.

Warm CLI Route: compact prompt to the fastest healthy installed CLI, using cached paths, cached environment, and preloaded system prompt.
BYOK Fast Lane: optional direct provider API path for users who explicitly add their own key and want lower process overhead or streaming.
Failover Route: if the selected backend misses budget, try another healthy configured backend when doing so will still beat the timeout.
Error With Original Preserved: if no backend succeeds, leave the input intact and provide a specific recovery message.

The user gets one final output. Sharpie should not show multiple candidate rewrites or expose provider churn.

Hot Path

The hotkey path must not perform slow discovery.

HotkeyService receives Command-/.
InvocationCoordinator immediately opens the HUD or Command Bloom.
SelectionService attempts selected-text capture with a strict timeout.
ContextPackBuilder builds from ContextSnapshotStore, not fresh filesystem scans.
PromptAssembler builds a compact rewrite request.
BackendRouter chooses the fastest healthy backend.
RewriteRunner invokes the backend with a strict timeout.
ResultCommitter replaces selection or copies to clipboard.

Background Path

Work that can be done before the user presses the hotkey should happen before the user presses the hotkey.

BackendRegistry detects available CLIs at launch and when settings opens.
BackendReadinessCache runs cheap version/auth probes outside the hotkey path.
BackendLatencyStore records recent success, failure, and latency data.
SystemPromptLoader loads and caches the prompt at launch.
ContextSnapshotStore keeps recent frontmost app, clipboard metadata, active project hint, git branch, changed-file names, and project capsule excerpts.
ProjectInstructionProvider caches small excerpts keyed by path and modification time.
GitContextProvider refreshes branch and changed-file names with a TTL. It never blocks invocation.
FileChangeMonitor uses macOS FSEvents for onboarded projects, marks changed files dirty, and debounces updates by roughly 2 to 5 seconds.
SymbolIndexer incrementally reparses dirty files in the background.
RepoMapBuilder refreshes compact repo maps outside the hotkey path.

No background job should collect hidden content or index entire projects.

Prompt Assembly

Local code should prepare the model to succeed quickly. It should not generate the final rewrite with templates.

Prompt assembly should:

classify the intent family for prompt shaping only
choose the right output contract: Build, Debug, Review, Plan, or Pitch
include the smallest useful Context Pack
include repo-map excerpts only when they help
enforce the context budget
preserve the user's original intent and phrasing
request exactly one final rewritten prompt or task brief

Example input:

fix settings weirdness

Example context:

Project: Sharpie
Changed files: SettingsView.swift, AppPreferences.swift

Example backend prompt shape:

Rewrite the user's rough intent into one excellent Debug task brief.
Use the project facts and changed-file hints below, but do not mention irrelevant context.
Never ask a clarifying question.
Return only the final rewritten prompt.

This is not allowed:

Generating a final canned template locally and skipping the AI backend because the input matched "fix ...".

AI Backends

Backends are the core rewrite engine. They are just not allowed to make the product feel stuck.

Default backend path:

Claude Code CLI: claude
Codex CLI: codex
Gemini CLI: gemini

Optional BYOK Fast Lane:

User explicitly chooses a direct provider.
User supplies their own API key.
Secrets are stored only with explicit consent, preferably in macOS Keychain, with an environment-variable option for users who do not want stored keys.
Sharpie may make direct provider API calls only for the configured BYOK provider.
BYOK must never be required for first run.

Backend prompts must be compact. Context Pack serialization should be short, structured, and aggressively budgeted.

Project Indexing

Project indexing exists to make the Context Pack smarter without making the hotkey slower.

Rules:

On project onboarding, run an initial lightweight scan only.
The initial scan may collect file paths, languages, basic project metadata, and shallow symbols, but it must not block the user from invoking Sharpie.
While Sharpie is running, use macOS FSEvents to mark projects dirty.
Debounce file changes by roughly 2 to 5 seconds.
Incrementally reparse only changed files.
On hotkey, use the latest cached index even if slightly stale.
If the index is stale, continue and include changed-file hints internally.
Background indexing must never block UI, selected-text capture, prompt assembly, or backend invocation.
Cache data must be clearable from settings or project management UI.

Repo Map

Use an aider-style repo map as the first code-intelligence strategy.

The repo map should be deterministic and concise: important files, classes, functions, signatures, imports, and dependency edges selected to fit a small context budget.

V1 should favor simple, explainable ranking:

selected text and explicit file names
changed files
recently active files
project capsule hints
symbol names matching the user's intent
central files with many local references

Do not build embeddings, full semantic search, or whole-repo AI summaries in V1. Deterministic repo map first. AI summaries only later if deterministic maps fail to produce useful prompts.

Parsing direction:

Tree-sitter is the preferred direction for fast local multi-language parsing and incremental symbol extraction.
SourceKit or IndexStoreDB can be added later for deeper Swift-specific intelligence.
SCIP can be considered later as a language-agnostic code intelligence interchange format.

Context Budgeting

Context must be budgeted before it reaches the backend prompt.

V1 target: 500 to 1,200 tokens.
V2 maximum: 2,000 tokens.
Never dump whole files by default.
Prefer symbols, signatures, file paths, changed-file hints, and project capsule excerpts over prose summaries.
If budget is tight, keep user input, selected text, project capsule facts, and changed-file hints before repo-map details.

Context Pack V1

Ship the smallest version that creates a visible jump in quality.

Required:

selected text
manually typed input
clipboard text, only when useful and recent
frontmost app name
selected backend or route
intent family, for prompt shaping only

Preferred next:

git repo path, branch, and changed file names when the frontmost app or terminal makes the project detectable
root AGENTS.md, CLAUDE.md, and README.md excerpts
.sharpie/context.md
.sharpie/preferences.md
.sharpie/recent-decisions.md
.sharpie/ignore
cached repo-map excerpts for onboarded projects

Deferred:

full selected-text replacement in every app
editor-specific integrations
screenshots
whole-repo semantic indexing
embeddings or vector search
whole-repo AI summaries
full-file context dumping

Project Capsules

A Project Capsule is a small human-readable folder that tells Sharpie how to think about a project.

.sharpie/
  context.md
  preferences.md
  recent-decisions.md
  ignore

`.sharpie/context.md`

Stable facts:

what the project is
tech stack
important files
non-goals
product constraints

`.sharpie/preferences.md`

How outputs should feel for this project:

concise or detailed
engineering-heavy or product-heavy
default test expectations
tone and style constraints

`.sharpie/recent-decisions.md`

Short human-maintained notes:

decisions made
tradeoffs accepted
things not to reopen

`.sharpie/ignore`

Human-maintained ignore rules for Sharpie project memory and indexing.

Use gitignore-style patterns where possible.
Always respect common generated directories by default, such as .git, node_modules, .build, build, DerivedData, .next, dist, and dependency/vendor caches.
Always exclude obvious secrets and environment files by default.
The ignore file narrows Sharpie's context; it does not override the privacy hard-no list.

Project Capsules are optional. Sharpie should work without them.

Onboarding should offer to create or update these files, but the user should be able to skip onboarding and still use instant rewrite.

Project Registry And Cache

ProjectRegistry tracks projects the user has explicitly selected or approved.

For each onboarded project, Sharpie stores generated cache under:

~/Library/Application Support/Sharpie/Projects/<project-hash>/

The project hash should be derived from the canonical local path. The cache directory may contain:

manifest.json: schema version, project path, display name, created/updated timestamps, index status, and cache metadata
symbols.db: extracted symbols, signatures, imports, and references
files.db: file metadata, hashes, language hints, and ignore decisions
graph.json: compact dependency or reference graph
last-indexed.json: indexing timestamps, dirty files, errors, and stale status

Cache rules:

Generated cache is not source of truth.
Generated cache must be safe to delete and rebuild.
Generated cache should never be written into .sharpie/ by default.
Cache contents may include sensitive file names or symbols, so they must remain local and clearable.
Do not include cache contents in backend prompts directly. ContextCompiler must select and budget relevant excerpts.

Backend Strategy

Sharpie is CLI-first. It shells out to local AI CLIs the user already has installed and authenticated.

Detection order:

Claude Code: claude
Codex CLI: codex
Gemini CLI: gemini

The user can override the active backend in settings.

Sharpie does not manage auth. If auth expires, Sharpie tells the user to run the CLI once in Terminal.

Backends are the rewrite engine. The local app makes them fast by caching context, shrinking prompts, avoiding hot-path discovery, tracking backend health, and routing to the fastest healthy option.

Optional BYOK exists for users who want a faster direct-provider path or do not want to depend on CLI behavior. It is advanced, opt-in, and never required.

Settings

Keep settings boring.

Required:

active backend picker
hotkey recorder
launch at login toggle
history toggle, off by default

Maybe later:

Context Pack source toggles
Project Capsule status
selected-text replacement permission status
BYOK Fast Lane provider and key management
performance mode: Auto, Prefer CLI, Prefer BYOK

Do not add a first-run API-key wall, account screens, cloud sync settings, team settings, or visible mode pickers for rewrite intent. BYOK settings belong behind an advanced path.

Privacy And Security

Sharpie should be boringly trustworthy.

No Sharpie-owned network calls.
No telemetry.
No analytics.
No crash reporter.
No update checker.
No accounts.
No required API keys.
Optional BYOK secrets may be stored only with explicit user consent, preferably in macOS Keychain, and must never be logged or synced.
No hidden project indexing.
No context collection that the user could not reasonably infer from invoking the hotkey.
No slow background process that crawls the user's filesystem.
No Sharpie-owned network calls unless BYOK Fast Lane is explicitly enabled.

Context Pack content should be inspectable during development and easy to reason about in code.

Architecture

Expected structure:

Sources/Sharpie/
  Backend/
    AIToolBackend.swift
    BackendDetector.swift
    BackendLatencyStore.swift
    BackendReadinessCache.swift
    BackendRegistry.swift
    BackendRouter.swift
    BYOKProviderBackend.swift
    ClaudeCodeBackend.swift
    CodexBackend.swift
    GeminiBackend.swift
    RewriteRunner.swift
    SubprocessRunner.swift
  Context/
    ContextPack.swift
    ContextPackBuilder.swift
    ContextSnapshotStore.swift
    ContextBudgeter.swift
    ContextCompiler.swift
    ClipboardContextProvider.swift
    FrontmostAppContextProvider.swift
    GitContextProvider.swift
    ProjectCapsuleProvider.swift
    ProjectInstructionProvider.swift
  Project/
    FileChangeMonitor.swift
    ProjectCapsuleManager.swift
    ProjectIndexStore.swift
    ProjectRegistry.swift
    RepoMapBuilder.swift
    SymbolIndexer.swift
  Rewrite/
    IntentRouter.swift
    PromptAssembler.swift
    RewriteRequest.swift
    RewriteResult.swift
  Services/
    ClipboardService.swift
    HotkeyService.swift
    LaunchAtLoginService.swift
    SelectionService.swift
    SystemPromptLoader.swift
  State/
    InvocationCoordinator.swift
    SharpenViewModel.swift
  Views/
    CommandBloomView.swift
    ContextReceiptView.swift
    SharpenView.swift
    SettingsView.swift

The view model should ask for a rewrite. It should not know how selected text is captured, context is collected, prompts are assembled, or backend routing is performed.

Milestones

Milestone 1: Command Bloom + CLI Rewrite

premium floating Command Bloom UI
global hotkey
fallback input window
compact prompt assembly
Claude Code, Codex, and Gemini subprocess backends
backend readiness cache
strict backend timeout
auto-copy
no clarifying questions

Milestone 2: Fast Backend Router

backend latency store
fastest healthy backend selection
failover when budget allows
compact Context Pack serialization for backend prompts

Milestone 3: Optional BYOK Fast Lane

advanced BYOK settings
direct provider backend abstraction
explicit consent for API key storage
Keychain or environment-variable secret source
streaming where provider supports it

Milestone 4: Context Pack Cache

clipboard awareness
frontmost app name
git branch and changed-file names from cached snapshots
project instruction excerpts
explicit Context Receipt UI

Milestone 5: Selection-First Flow

selected-text capture
selected-text replacement where safe
clipboard fallback when replacement fails
permission-aware UX

Milestone 6: Project Capsules

optional .sharpie/ files
project-specific preferences
recent decision notes
prompt shaping from capsule content

Milestone 7: Project Registry + Repo Map

explicit project onboarding
generated cache under Application Support
initial lightweight scan
FSEvents dirty tracking
debounced incremental symbol indexing
deterministic repo map
ContextBudgeter with 500 to 1,200 token V1 budget
clear project cache action

Success Metrics

Sharpie works if:

Vikky uses it daily for two weeks.
It saves a meaningful AI turn at least once per day.
Hotkey to visible UI is under 100ms.
Hotkey to backend dispatch is usually under 500ms.
CLI rewrites usually finish under 3s.
BYOK Fast Lane rewrites usually finish under 2s when enabled.
No hotkey invocation blocks on git, filesystem scans, backend detection, or auth probing.
No hotkey invocation blocks on project indexing.
Onboarded projects produce better task briefs without making the app feel heavier.
The rewritten prompt is specific enough that the target AI can start useful work without asking a follow-up.
The product still feels small after adding context.

The product is wrong if:

the user has to manage it
outputs feel generic
context feels creepy
output feels template-like
settings grow faster than usefulness
Sharpie becomes another place to chat
the user waits because Sharpie is doing local discovery it could have done earlier

Hard No List

required direct provider APIs
required API keys
first-run API-key wall
storing optional BYOK secrets outside Keychain or explicit environment-variable configuration
telemetry
analytics
crash reporting
update checks
accounts
cloud sync
prompt marketplace
team workspace
browser extension in v1
full-computer indexing
automatic background capture
user-visible intent mode picker
clarification loop
blocking the hotkey path on backend startup
blocking the hotkey path on git or filesystem scans
blocking the hotkey path on project indexing
generated indexes inside .sharpie/ by default
embeddings, vector search, or whole-repo AI summaries in V1
whole-file context dumping by default
deterministic local templates as the primary rewrite engine

The Bar

Every feature should answer this:

Does this make one rough thought become one excellent next action faster?

If yes, consider it.

If no, cut it.

FilesExpand file tree

PRD.md

Latest commit

History