ScopePilot

Local-first, approval-first desktop assistant for IT Project Managers.

ScopePilot helps a PM turn project inputs into structured, reviewable outputs:

• requirements, milestones, and scope notes
• change requests from client emails and meeting notes
• backlog drafts, task drafts, risks, and questions
• project chat with project-scoped memory
• sprint-aware and milestone-aware status support
• Jira-ready drafts after explicit approval

Primary PM workflow

ScopePilot is designed around a realistic PM flow:

1. a document, e-mail, note, or client question enters a project
2. ScopePilot classifies it (information, change request, risk, question, draft task)
3. ScopePilot explains why it interpreted it that way
4. the PM reviews and edits the draft output
5. only after approval does anything move toward external systems like Jira

The product should feel like a calm, modern project cockpit — not a noisy chatbot wrapper.

Core principles

1. Assistant, not autopilot — nothing impactful happens without approval.
2. Project isolation first — each project has its own memory, documents, RAG namespace, chats, and settings.
3. Explainability by default — every proposal should include why, source references, and uncertainty.
4. Local-first foundation — workspace, files, local DB, and local model runtime are first-class.
5. Modular from day one — new modules, providers, and integrations must fit the documented architecture.
6. Docs stay in sync with code — every new folder or module must be documented.

Recommended stack

• Desktop app: Tauri 2 + React + TypeScript + Tailwind + shadcn/ui
• Backend: FastAPI + Pydantic + SQLAlchemy + Alembic
• Operational DB: SQLite
• Vector store: Qdrant local (server mode later if needed)
• AI runtime: LM Studio by default, plus optional external providers
• State and contracts: typed DTOs, explicit workflows, approval queues
• Internationalization: modular locale files (pl, en) with room for more

What this repository contains

This repository is a foundation pack for building ScopePilot with coding agents such as Cursor, Claude Code, Codex, or similar tools.

It contains:

• architecture and repository structure
• roadmap divided into phases
• module specifications
• UI/AI behavior specifications
• workspace and storage rules
• API and database contracts
• documentation rules for coding agents
• screen specs and action catalog
• provider and MCP settings strategy
• development setup guides for Cursor and VS Code
• starter folders for desktop and backend implementation

Start here

1. Read AGENTS.md
2. Read CLAUDE.md
3. Read docs/index.md
4. Read docs/roadmap/index.md
5. Read docs/development/cursor-setup.md or docs/development/vscode-setup.md
6. Implement from Phase 1 in order

Roadmap phases

• Phase 1 — Foundation
  • workspace root, storage layout, settings shell, project registry
  • approval model, contracts, DB, ingestion skeleton, provider settings
• Phase 2 — PM workflows
  • inbox, change analyzer, project chat, backlog drafts, approvals, Jira drafts
• Phase 3 — Extensions
  • sprints, roadmap visualization, reports, additional providers, MCP actions, updater, plugins

Important operational rules

• Every new folder added by an agent must be:
  • added to docs/architecture/folder-catalog.md
  • reflected in docs/architecture/repository-structure.md if it changes structure
  • briefly explained in the relevant module or architecture doc
  • mentioned in STATUS.md if part of a roadmap item
• Every new external integration must support:
  • explicit configuration
  • secure secret storage
  • dry-run / preview mode
  • audit logging
  • approval before write actions

External model strategy

Default path:

• local LM Studio for day-to-day work

Optional path:

• review / verify / compare answers using external providers through official APIs
• supported provider families:
  • OpenAI Responses API
  • Anthropic Messages API
  • other OpenAI-compatible runtimes

Do not build the core product around browser login automation to consumer chat apps. Prefer stable API integrations instead.

See:

• docs/ai/providers.md
• docs/ui/screen-specs/settings.md
• docs/security/secrets-and-mcp.md

License

Private project scaffold for internal development.

Agent-ready repository rules

• New folders must be added to docs/architecture/folder-catalog.md.
• New public capabilities must be added to docs/architecture/capability-catalog.md.
• Fresh sessions should follow docs/agents/session-start.md automatically before implementation.

See also:

• docs/product/vision.md
• docs/ui/design-system.md
• docs/development/agent-tooling.md