DiscoveryKit

A CLI tool to install Cursor discovery prompts templates into your repository. Sync results to Notion with MCP.

What is this?

This tool installs a comprehensive set of discovery prompts for Cursor AI, designed to help you document and understand brownfield codebases. The prompts guide you through:

• Repository indexing
• Feature inventory
• Domain storytelling
• Architecture analysis
• Dependency analysis
• C4 diagrams
• Code quality assessment
• Security posture
• CI/CD pipelines
• Data models
• Integrations
• Observability
• Risks & decisions
• Fact-checking

Installation & Usage

Quick Start - Interactive Wizard (Recommended) 🪄

Run this command in your project directory:

npx davivilela/discoverykit

You'll be greeted with an interactive wizard that guides you through the installation:

Step 1: Choose Your Action

✨ Welcome to DiscoveryKit! ✨

What would you like to do?

  1. 📦 Install all commands (recommended for first-time users)
  2. 🎯 Custom selection (choose specific commands)
  3. 🔗 Setup Notion MCP integration
  4. ❌ Cancel

Step 2: Select Commands (if you chose Custom Selection)

You'll see a list of all 15 discovery commands with checkboxes:

• Use ↑/↓ arrow keys to navigate
• Press Space to select/deselect commands
• Press Enter to confirm your selection

Step 3: Setup Notion MCP (if you chose Notion integration)

The wizard will:

1. Configure Notion MCP in your project (.cursor/mcp.json)
2. Provide next steps for authorization
3. Optionally return to the menu to install commands

💡 The MCP config is stored locally in your project and can be committed to version control for team sharing.

Step 4: Confirm Installation

Review your selection and confirm before installation begins.

Non-Interactive Modes

Install everything without prompts:

npx davivilela/discoverykit --all

Install everything and overwrite existing files:

npx davivilela/discoverykit --all --force

File Overwrite Prompts

When a file already exists, you'll be prompted:

⚠️  File already exists: .cursor/commands/discovery/discovery-01-repo-index.md
    Override? (y/N/yes-to-all):

Options:

• n or N (default) - Skip this file, keep the existing version
• y or yes - Override this file with the new version
• yes-to-all or a - Override this and all remaining files without asking again

Global Installation

If you want to use it across multiple projects:

npm install -g davivilela/discoverykit
discoverykit

Command Line Options

npx davivilela/discoverykit [options]

Options:

• -a, --all - Install all commands without interactive prompts
• -f, --force - Overwrite all existing files without prompting
• --setup-notion-mcp, --notion - Configure Notion MCP in Cursor settings
• -h, --help - Show help message

Examples:

# Interactive wizard (default)
npx @davivilela/discoverykit

# Install all commands
npx @davivilela/discoverykit --all

# Install all, overwrite existing files
npx @davivilela/discoverykit --all --force

# Setup Notion MCP integration
npx @davivilela/discoverykit --setup-notion-mcp

# Show help
npx @davivilela/discoverykit --help

Available Commands

DiscoveryKit includes 15 specialized discovery prompts plus a Notion export command:

| # | Command | Description | |---|---------|-------------| | 1 | Repository Index | Map the codebase structure and key files | | 2 | Feature Inventory | Catalog all user-facing features | | 3 | Domain Storytelling | Document business domain and workflows | | 4 | Architecture Overview | Analyze system architecture and patterns | | 5 | Dependency Analysis | Map internal and external dependencies | | 6 | C4 Diagrams | Create context and container diagrams | | 7 | Code Quality Assessment | Evaluate code health and technical debt | | 8 | Security Posture | Review security practices and vulnerabilities | | 9 | CI/CD Pipelines | Document build and deployment processes | | 10 | Data Model | Map database schemas and entities | | 11 | Integrations | Document external service integrations | | 12 | Observability | Review logging, monitoring, and alerting | | 13 | Risks & Decisions | Identify technical risks and ADRs | | 14 | Fact Check | Validate and verify discovery findings | | 15 | Client Report | Generate executive summary report | | 16 | Discovery Kickoff | Orchestration command to run all steps | | 17 | Export to Notion | Upload all discovery docs to Notion workspace |

File Structure

Commands are installed to .cursor/commands/:

.cursor/
├── mcp.json                           # Notion MCP config (if configured)
└── commands/
    ├── discovery-kickoff.md           # Orchestration command (runs all 14 steps)
    ├── export-to-notion.md            # Export command (uploads to Notion)
    └── discovery/
        ├── discovery-01-repo-index.md
        ├── discovery-02-feature-inventory.md
        └── ... (all selected commands)

How to Use the Discovery Prompts

Option 1: Full Discovery (Orchestrated)

1. Open your project in Cursor
2. Press Cmd+L (Mac) or Ctrl+L (Windows/Linux) to open AI chat
3. Type /discovery-kickoff and press Enter
4. The AI will run all 14 discovery steps in order and generate documentation in /wiki/discovery/

Option 2: Individual Steps

Run specific discovery prompts as needed:

1. Open Cursor AI chat (Cmd+L or Ctrl+L)
2. Type / to see your commands
3. Select the specific discovery step you want (e.g., /discovery-04-architecture)
4. The AI will execute that step and create the corresponding wiki document

Option 3: Export to Notion

After running discovery, share results with stakeholders:

1. Open Cursor AI chat (Cmd+L or Ctrl+L)
2. Type /export-to-notion
3. The AI will create a Notion page hierarchy with all discovery docs
4. Share the Notion link with your team for browsing, commenting, and linking to tasks

Output

All discovery steps generate Markdown documentation in /wiki/discovery/ within your repository:

• /wiki/discovery/01-repo-index.md
• /wiki/discovery/02-feature-inventory.md
• /wiki/discovery/03-domain-storytelling.md
• ... and so on

📤 Syncing to Notion

You can sync your discovery documentation to Notion using Notion MCP with Cursor AI.

Quick Setup

Option 1: Interactive Wizard

Run the CLI and select "Setup Notion MCP integration" from the menu:

npx @davivilela/discoverykit

Option 2: Direct Command

npx @davivilela/discoverykit --setup-notion-mcp

Both methods will:

• Create/update your Cursor MCP configuration at .cursor/mcp.json (in your project)
• Add the Notion MCP server configuration
• Provide next steps for authorization
• Create a project-specific config (can be committed to git for team sharing)

Manual Setup

1. Connect Notion to Cursor:

   • Open Cursor Settings (Cmd/Ctrl + ,)
   • Go to Features → Model Context Protocol
   • Click "Add MCP Server"
   • Enter URL: https://mcp.notion.com/mcp
   • Authorize your Notion workspace

2. Sync Discovery Docs:

   After running discovery prompts, open Cursor AI (Cmd/Ctrl + L) and ask:

   Please create a new Notion database called "Codebase Discovery" 
   and upload all the markdown files from /wiki/discovery/ as separate pages.
   Organize them by number and maintain the formatting.

   Or for individual files:

   Upload /wiki/discovery/04-architecture.md to my Notion workspace 
   as a new page in the Engineering section.

Benefits of Using Notion

• Collaborative editing — Share and edit discovery docs with your team in real-time
• Rich formatting — Notion's UI makes complex diagrams and tables easier to navigate
• Linking & references — Connect discovery pages to related projects, tasks, and people
• Comments & feedback — Team members can add questions and suggestions inline
• Search & organization — Better discoverability across all your documentation

Example Prompts for Cursor AI

Once Notion MCP is connected, you can use these prompts:

Create a Notion page hierarchy for my discovery docs:
- Parent page: "Project Discovery - [Project Name]"
- Child pages for each of the 14 discovery documents
- Add a table of contents on the parent page

Upload the architecture and security docs to Notion 
and create a linked database to track the risks mentioned in discovery-13

Create a Notion dashboard that summarizes:
- Top 5 risks from discovery-13-risks-decisions.md
- Architecture diagram from discovery-04-architecture.md
- Integration list from discovery-11-integrations.md

🚀 Quick Export (One Command)

We've created a dedicated export command for you:

/export-to-notion

This command will:

1. Create a parent page: "Project Discovery – {your-project-name}"
2. Upload all 14 discovery documents as child pages
3. Preserve all formatting, code blocks, tables, and diagrams
4. Add a table of contents for easy navigation
5. Include project metadata (branch, commit, repo URL)

Example output:

✅ Discovery Export Complete!

📊 Summary:
  • Parent page created: "Project Discovery – MyApp"
  • Child pages uploaded: 14/14
  
🔗 Notion Link:
  https://notion.so/Project-Discovery-MyApp-abc123

📝 Now stakeholders can browse, comment, and link risks to their task tracker!

Requirements

• Node.js: 14.0.0 or higher
• Cursor IDE: Latest version recommended
• A git repository (for best results)

Updating

To get the latest version of the prompts:

npx davivilela/discoverykit@latest

Contributing

Issues and pull requests are welcome!

License

MIT