Skip to content

PRD.md

Latest commit

 

History

History
1374 lines (969 loc) · 33.3 KB

PRD.md

File metadata and controls

1374 lines (969 loc) · 33.3 KB
Raw

DevMap — Product Requirements Document

Single source of truth for DevMap development.
Before adding any feature or changing any priority — read this first.

Table of Contents

  1. Product Identity
  2. Problem
  3. Vision
  4. Product Positioning
  5. Core Philosophy
  6. Target Users
  7. Assumptions to Validate
  8. MVP Goal
  9. Core Commands — MVP
  10. Generated Files
  11. AI Strategy
  12. Language Strategy
  13. Static Analysis Strategy
  14. Snapshot Schema Strategy
  15. Context Builder Strategy
  16. Token Benchmarking Strategy
  17. Token & Caching Strategy
  18. Terminal UX Strategy
  19. Error Handling Strategy
  20. Cross-Platform Testing Strategy
  21. Future Commands
  22. Future AI Modes
  23. Repository Structure
  24. Success Metrics
  25. Risks & Mitigations
  26. Launch Checklist
  27. License

1. Product Identity
Product Name DevMap
Package Name devmap
Tagline Understand any codebase in minutes, not days.
Short Description AI-powered CLI to analyze, map, and explain codebases.

2. Problem

Modern AI tools can generate code faster than developers can understand it.

Developers frequently encounter:

  • Unfamiliar codebases with little or no documentation
  • Long onboarding time when joining new projects
  • AI-generated projects with unclear structure
  • Large projects with hundreds of files
  • Repeated manual explanation when using AI tools
  • Context window limitations when asking AI about codebases
  • AI agents that must repeatedly explore project files from scratch

Reading every file manually is slow, inefficient, and does not scale.

3. Vision

DevMap becomes the first tool developers run after cloning a repository.

The goal is not to replace AI coding assistants. The goal is to help developers and AI agents understand unfamiliar codebases faster through:

  • Project mapping
  • Static analysis
  • Architecture discovery
  • Onboarding guidance
  • Reusable project snapshots
  • Documentation generation
  • Code relationship tracing

DevMap is the project understanding layer between developers, codebases, and AI agents.

4. Product Positioning

DevMap is not an AI coding assistant.

AI coding assistants help developers write code.
DevMap helps developers understand code that already exists.

DevMap is complementary to:

  • Cursor
  • Claude Code
  • OpenAI Codex
  • Gemini CLI
  • GitHub Copilot
  • Other AI coding agents

DevMap should not position itself as a direct competitor to those tools.

Instead, DevMap creates structured project context that can help humans and AI agents understand a project faster.

Why Not Just Use AI Directly?

Without DevMap, AI agents and chat tools often need to:

  • Explore the repository from scratch
  • Guess relevant files from names and partial context
  • Rebuild project understanding on every new session
  • Spend tokens on exploration before solving the actual task

With DevMap, users get:

  • A reusable project snapshot
  • Static-analysis-backed project structure
  • Important files and relationships
  • Context that can be used across different AI tools
  • A project map that persists beyond a single AI session

DevMap is not a replacement for AI. It is the context layer before AI.

5. Core Philosophy

DevMap is not AI-first.

80% Static Analysis
20% AI Interpretation

LLMs should not read the entire project.
LLMs should interpret analysis results generated by DevMap.

The static analysis engine is the foundation of the product.
AI is an enhancement layer, not the primary engine.

Important Framing

Do not claim DevMap is token-efficient until benchmarked.

Use this framing before validation:

DevMap is designed to reduce repeated AI exploration by generating reusable project context.

Use stronger token-efficiency claims only after real benchmark results exist.

6. Target Users

Primary — Developers Working with AI

Developers who regularly use AI tools and need reusable, structured project context.

Examples:

  • Developers using AI Generatif like Chatgpt, Gemini, Claude, and similir Web-based chat AI
  • Developers using AI Agents like Claude Code, Codex, Gemini CLI, Cursor, and similar AI agents
  • Vibe coders working with AI-generated codebases
  • Developers returning to old projects after weeks or months
  • Freelancers working on unfamiliar client repositories
  • Developers frequently cloning and exploring open-source projects
  • Engineers who want AI tools to spend less time exploring and more time solving problems

Secondary — Individual Developers

Developers who need faster project understanding and onboarding.

Examples:

  • IT students joining team projects
  • Solo developers managing multiple projects
  • Developers inheriting existing codebases
  • Builders maintaining long-term side projects

Tertiary — Small Teams

Teams that need shared project understanding without maintaining documentation manually.

Examples:

  • Teams onboarding new members frequently
  • Fast-moving product teams
  • Startup teams with evolving architectures
  • Hackathon teams that need rapid project understanding
  • Teams using AI tools as part of their development workflow

Not For

DevMap may provide limited value for:

  • Very small projects with simple structures
  • Single-purpose scripts and throwaway prototypes
  • Developers who already know every part of their codebase and rarely use AI tools
  • Users expecting DevMap to generate, refactor, or write code
  • Users looking for a replacement for AI coding assistants such as Cursor, Claude Code, or GitHub Copilot

Important Note

Even well-documented projects can benefit from DevMap.

Documentation explains a project.

DevMap creates structured, reusable context that helps both developers and AI tools understand a project faster and more consistently across sessions.

7. Assumptions to Validate

This section separates assumptions from proven facts.

Assumption Validation Method Status
DevMap reduces repeated AI exploration Compare raw-file prompting vs snapshot-based prompting using Groq usage data Not tested
DevMap reduces token usage meaningfully A/B benchmark on 3+ projects using Groq usage.prompt_tokens Not tested
Static analyzer is accurate for Next.js App Router Test against 5 real Next.js projects and manually review snapshot Not tested
Static analyzer is accurate for Express projects Test against 3 real Express projects Not tested
Context Builder can select relevant files correctly Manual review on 20 real questions Not tested
Developers want reusable project snapshots Early user feedback/interviews Not tested
Developers accept BYOK/API-key setup Observe first 10 external users Not tested
AGENTS.md append flow is acceptable Ask confirmation before modifying existing file Not tested
DEVMAP.md is useful for humans and AI agents Ask early users whether it helps them use DevMap Not tested

These assumptions must be validated before making strong public claims.

8. MVP Goal

A developer who has never seen a 200-file Next.js codebase can understand its main structure in under 10 minutes using DevMap.

MVP success means DevMap can:

  • Scan a project
  • Detect stack and structure
  • Identify important files
  • Generate a reusable snapshot
  • Explain high-level architecture
  • Answer basic project questions using the snapshot

9. Core Commands — MVP

Four core project commands plus one configuration command.

Nothing removed. Nothing added until MVP is shipped.

devmap init

Setup wizard. Runs once per machine/project.

Responsibilities:

  • Ask for AI provider
  • Ask for API key
  • Ask for an OpenRouter model, defaulting to openrouter/free on Enter
  • Validate API key
  • Save global config to ~/.devmap/config.json
  • Create .devmap/ project folder if needed
  • Add .devmap/ to .gitignore
  • Generate DEVMAP.md
  • Handle AGENTS.md safely
  • Detect basic project stack
  • Finish in under 30 seconds

Usage:

devmap init

Output:

DevMap Setup

Provider:   ✓ Groq
API Key:    ✓ Valid
Project:    ✓ Next.js detected

Config saved: ~/.devmap/config.json
Generated: DEVMAP.md
Updated: .gitignore

Run: devmap analyze

devmap analyze

Run static analysis, generate project snapshot, and output a readable project overview.

Supported stacks (MVP):

  • Next.js
  • Express
  • React

Responsibilities:

  • Scan file structure
  • Detect framework
  • Detect routes and API routes
  • Detect dependencies
  • Detect external services
  • Detect database/schema
  • Detect entry points
  • Identify critical files
  • Generate a lightweight agent index and per-feature navigation maps
  • Generate architecture overview
  • Save snapshot to .devmap/snapshot.json

Usage:

devmap analyze

devmap analyze uses the provider and model stored in ~/.devmap/config.json. Groq users choose a model during setup and can change it later with devmap config model <model-id>.

Generated files:

.devmap/index.json
.devmap/features/*.json
.devmap/snapshot.json

devmap doctor

Diagnostics command. Helps users debug setup and provides copy-pasteable output for filing issues.

Usage:

devmap doctor

Checks:

  • DevMap version
  • Node.js version
  • Package manager
  • Provider config
  • API key status
  • Selected model
  • Snapshot status
  • Project detection
  • OS/platform
  • Common permission issues

Example output:

DevMap Doctor

DevMap version    0.1.0               ✓
Node.js version   20.11.0             ✓
Provider          Groq                ✓
API key           valid               ✓
Model             openai/gpt-oss-20b  ✓
Snapshot          exists              ✓

No issues found.

devmap config model

Set a global Groq model override or restore automatic command-based routing.

devmap config model llama-3.1-8b-instant
devmap config model openai/gpt-oss-120b
devmap config model auto

The override applies to AI-powered commands. auto restores the defaults in the model routing table.

Machine-Readable Output

All MVP commands support --json for AI agents, scripts, and editor integrations:

devmap init --json
devmap analyze --json
devmap doctor --json
devmap config model auto --json

JSON mode rules:

  • stdout contains exactly one valid JSON document
  • no ANSI colors, Markdown rendering, box drawing, or progress text
  • runtime errors use a stable { "status": "error", "error": "...", "hint": "..." } shape
  • init --json is non-interactive and requires GROQ_API_KEY, OPENROUTER_API_KEY, or existing config
  • AI responses are buffered instead of streamed
  • human-readable output remains the default
  • package-manager wrappers may still write their own warnings to stderr

10. Generated Files

DevMap uses generated files to create reusable context for humans and AI agents.

DEVMAP.md

Generated during devmap init.

Purpose:

  • Explain how to use DevMap in this repository
  • Provide instructions for humans and AI agents
  • Tell AI agents how to read the project snapshot
  • Encourage DevMap-first workflows

Important:

  • Generated once during init
  • Not automatically regenerated by devmap analyze
  • Can be manually edited by the user
  • Should clearly say it is a DevMap usage/instruction file

Recommended header:

> This file explains how to use DevMap in this repository.
> For current project analysis, see `.devmap/snapshot.json`.

.devmap/index.json and .devmap/features/*.json

Generated by devmap analyze as the lightweight navigation layer for AI agents.

Preferred reading order:

  1. .devmap/index.json
  2. the relevant .devmap/features/*.json map
  3. source files listed in sourcePriority
  4. .devmap/snapshot.json only when more detail is required

The index must remain short and must not duplicate full dependency or change impact data.

The index project header includes framework, frameworks, projectType, and workspaceType. framework is the primary project framework and remains unknown for a CLI/library workspace without one primary web framework. frameworks lists frameworks detected in workspace packages, such as Astro in a landing app. Project type describes the primary shape such as node-cli, web-app, api-service, or library; workspace type distinguishes a monorepo from a single package. Its deterministic summary uses package description and detected capabilities instead of file-count filler.

criticalFiles is a start-here list, not an import-count leaderboard. It prioritizes executable entry points, CLI/feature orchestrators, and files that own detected flows before dependency popularity. Feature maps expose an ordered sourcePriority, while flow describes system actions rather than a second file list.

.devmap/snapshot.json

Generated by devmap analyze.

Purpose:

  • Fresh project analysis data
  • Reusable context for AI tools
  • Regenerated every time the project is re-analyzed
  • Full analysis archive and backward-compatible source for DevMap commands

Important:

  • This is the file that gets regenerated
  • It should contain structured metadata, not full raw project content
  • Should stay compact and predictable

AGENTS.md

DevMap may integrate with AGENTS.md if the project uses AI agents.

Rules:

If AGENTS.md does not exist:

  • DevMap can generate a basic file

If AGENTS.md already exists:

  • DevMap must not overwrite it
  • DevMap should ask before appending anything
  • Append only a small DevMap instruction block
  • The instruction should tell AI agents to read DEVMAP.md before starting

Example append block:

<!-- DevMap Instruction Block -->
## DevMap Context

Before working in this repository, read `DEVMAP.md` first.
For current project structure, use `.devmap/snapshot.json` if available.
<!-- End DevMap Instruction Block -->

11. AI Strategy

MVP Providers

Groq and OpenRouter.

Reasons:

  • Fast inference
  • Accessible globally
  • User provides their own API key
  • No DevMap backend required
  • OpenRouter users can choose any model their account can access

Provider Abstraction

Built from day one so adding providers later requires no major refactor.

AI provider logic must not be tightly coupled to commands.

Recommended structure:

ai/
├── ai-client.ts
├── providers/
│   ├── groq.ts
│   ├── openai.ts       ← placeholder
│   └── gemini.ts       ← placeholder
├── context-builder.ts
└── prompts.ts

Model Routing

Command Model Reason
analyze openai/gpt-oss-20b Balanced architecture interpretation
analyze fallbacks qwen/qwen3.6-27b -> llama-3.3-70b-versatile -> llama-3.1-8b-instant Keep snapshot enrichment available across model-specific limits

DevMap retries a rate-limited model up to three times, then advances through the command-specific chain. It also advances when a model is unavailable or returns a transient provider error. Authentication and malformed-request errors stop immediately. Duplicate model IDs are removed, including when a user-configured primary model also appears in the fallback chain. No raw provider errors are shown to users.

Model availability changes over time. Before changing the default routing, verify the current Groq model list and lifecycle status. Preview models must not be used as a primary default for a public DevMap release.

Groq setup lists the currently available Groq models after validating the API key. Users choose one with arrow keys and Enter; the selected model is stored as the user's preferred model.

OpenRouter setup asks for a model ID after validating the API key. Pressing Enter selects openrouter/free; entering another free or paid model stores that exact model as the user's preferred model. Explicit user selections take priority and are not replaced by DevMap's Groq routing chain. Users can change the selection later with devmap config model <model-id>; setting auto on OpenRouter restores the safe openrouter/free default.

User API Key Principle

  • Users provide their own API keys
  • DevMap has no backend server for MVP
  • API keys stored locally at ~/.devmap/config.json
  • DevMap never sends API keys to any DevMap-owned server
  • Requests go directly from user's machine to selected provider

12. Language Strategy

Default Behavior

language = auto

DevMap automatically detects the language used by the user.

User question language Response language
Bahasa Indonesia Bahasa Indonesia
English English

Applies To

  • devmap explain (future)
  • devmap onboarding
  • devmap docs (future)

CLI Metadata

Core CLI labels remain English regardless of language mode.

Examples:

  • Framework
  • Routes
  • Dependencies
  • Features
  • Entry Points
  • Critical Files

These are industry-standard terms familiar to developers worldwide.

Configuration

devmap config language auto
devmap config language en
devmap config language id

Language Rule Summary

Output Type Language
CLI labels English
Technical terms English where natural
AI explanation Same as user prompt
Generated docs Config language or detected
Error messages English
Help text English

13. Static Analysis Strategy

Static analysis runs before AI.

DevMap extracts useful structure without spending tokens.

Static analysis detects:

  • Files and folders
  • Framework
  • Dependencies
  • Routes and API routes
  • Imports and exports
  • Database/schema
  • External services
  • Entry points
  • Critical files

JavaScript and TypeScript files use a normalized ts-morph analyzer for imports, exports, symbols, and function metadata. Other source languages keep the heuristic analyzer, with a low-confidence fallback for unknown file types. The analyzer registry preserves the extension point for future parsers.

Results are converted into compact structured data before AI interpretation.

MVP Principle

Before building more commands, devmap analyze must produce a snapshot that is accurate enough on real projects.

The analyzer must be tested against:

  • DevMap itself
  • DevNote
  • One unfamiliar project
  • At least one Next.js App Router project
  • At least one Express project

14. Snapshot Schema Strategy

The snapshot schema is the contract between the analyzer and every command.

It must be defined early and kept stable.

Recommended MVP schema:

interface DevMapSnapshot {
  version: string;
  generatedAt: string;
  agentInstructions: {
    navigationPolicy: "index-first";
    defaultMode: "feature-map-first";
    maxInitialFiles: number;
    missingSnapshotAction: "run-devmap-analyze";
    staleSnapshotAction: "run-devmap-analyze-fresh";
    fallbackRule: string;
  };
  project: {
    name?: string;
    root: string;
    framework: "nextjs" | "express" | "react" | "node" | "unknown";
    language: "typescript" | "javascript" | "mixed" | "unknown";
    packageManager: "pnpm" | "npm" | "yarn" | "bun" | "unknown";
  };
  entryPoints: EntryPoint[];
  criticalFiles: CriticalFile[];
  routes: RouteInfo[];
  apiRoutes: ApiRouteInfo[];
  dependencies: DependencyInfo[];
  externalServices: ExternalServiceInfo[];
  database?: DatabaseInfo;
  features: FeatureInfo[];
  flows: FlowInfo[];
  onboarding: {
    recommendedPath: string[];
  };
  changeImpact: Record<string, {
    impacts: string[];
    dependents: string[];
  }>;
  fileIndex: Record<string, {
    hash: string;
    imports: string[];
    exportedSymbols: string[];
    topFunctions: Array<{
      name: string;
      kind: "function" | "const" | "class" | "method";
      line: number;
      exported: boolean;
      async: boolean;
    }>;
    lines: number;
    purpose?: string;
    scope: "api" | "ui" | "database" | "config" | "service" | "cli" | "test" | "docs" | "unknown";
    featureRefs: string[];
    searchTerms: string[];
    importance: number;
  }>;
}

Snapshot Rules

  • Snapshot must not contain full raw project source by default
  • Snapshot should be compact
  • Snapshot should be deterministic
  • Snapshot must include a schema version
  • Future schema changes must be versioned
  • File index entries should include compact navigation metadata such as purpose, responsibility scope, exported symbols, top functions/code symbols, feature references, search terms, and importance. These fields help future onboarding output and future flow generation without storing full raw source.
  • Flow metadata should include compact high-confidence feature flows and request/API flows derived from routes and local dependency edges.
  • Feature metadata should expose a primary entry point and a short business flow when DevMap can infer one from routes or dependency edges.
  • Snapshot should include a lightweight onboarding path and file-level change impact map for future generated docs and safer AI-assisted edits.
  • Snapshot should include compact machine-readable agent instructions. The complete agent navigation contract belongs in generated DEVMAP.md.
  • .devmap/index.json and feature maps are derived navigation artifacts, not a replacement for the full versioned snapshot.
  • AI-generated file purpose and search terms must be batched and optional. Analyze must continue if enrichment fails.

15. Context Builder Strategy

The Context Builder selects only relevant files before sending anything to AI.

MVP Approach

Do not use embeddings or semantic search in MVP.

Use pragmatic heuristics first:

  • File path matching
  • Keyword matching
  • Import/export matching
  • Dependency matching
  • Known framework conventions

Example:

User asks:

how does authentication work?

Extract likely keywords:

auth, authentication, login, session, token, middleware

Match against:

  • File paths
  • File names
  • Exports
  • Imports
  • Dependencies
  • Known services like next-auth, jwt, clerk, supabase/auth

Selected context:

auth.ts
middleware.ts
session.ts
app/api/auth/*

Not selected:

entire project

Relevance Confidence And Query Expansion

  • Direct query keywords are extracted separately from generic intent words such as add, change, explain, or find.
  • When AI configuration is available, the context builder may run a lightweight retrieval-only model call that returns up to 10 generic technical terms for better recall.
  • Expanded terms improve ranking, but direct keyword matches remain stronger than inferred matches.
  • Files below the minimum relevance score of 25 are excluded.
  • Confidence is high at 70+, medium at 40+, and low below 40.

Goals

  • Reduce repeated exploration
  • Reduce token usage
  • Improve answer relevance
  • Avoid context overload

Validation

The Context Builder must be manually tested using at least 20 questions.

16. Token Benchmarking Strategy

Token efficiency is an assumption until proven.

Benchmark Method

Use Groq for both scenarios.

Do not compare Groq usage against Codex/Claude Code UI percentages because those are not exact and not comparable.

Scenario A — Raw File Prompting

Send selected raw files or large raw project context directly to Groq.

Record:

{
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "total_tokens": 0
}

Scenario B — DevMap Snapshot Prompting

Send DevMap snapshot + selected relevant context to Groq.

Record the same usage fields.

Test Projects

  • DevMap
  • DevNote
  • One unfamiliar public/open-source project

Test Questions

Use the same questions for both scenarios.

Example:

  • How does authentication work?
  • Where is payment logic handled?
  • Explain the main user flow.
  • Which files are most important for onboarding?
  • Where is database access implemented?

Success Criteria

DevMap may claim token efficiency only if benchmark results show meaningful reduction.

Before that, use careful wording:

Designed to reduce repeated exploration and provide reusable project context.

17. Token & Caching Strategy

Token Rules

  • Do static analysis first
  • Never send raw full project to AI
  • Send compact JSON summary where possible
  • Cache snapshots and reuse them

Expected Behavior

Token Usage
First analyze Higher
Subsequent analyze with no project changes Lower — reuse snapshot/cache

Cache Files

MVP:

.devmap/snapshot.json

Future optimization:

.devmap/cache.json

Potential future cache content:

  • File hashes
  • Dependency graph
  • Extracted metadata
  • Last analysis result per file

18. Terminal UX Strategy

DevMap should feel like a modern developer CLI.

Inspired by:

  • Vercel CLI
  • Railway CLI
  • GitHub CLI
  • Claude Code

Use:

  • Aqua/cyan as primary accent color
  • Clean spacing
  • Short sections
  • Progress feedback
  • Actionable errors
  • Copy-pasteable diagnostics

Avoid:

  • Giant ASCII art
  • Excessive emojis
  • Hacker-style visuals
  • Long unreadable walls of text
  • Raw stack traces

19. Error Handling Strategy

DevMap must never fail silently.

Bad:

Error: 429

Good:

Rate limit reached.

DevMap will retry in 12 seconds.

Tip: Choose a smaller model with devmap config model <model-id> for lower token usage.

All error messages must be:

  • Understandable
  • Actionable
  • Non-scary
  • Free of raw stack traces

Required Error Cases

Handle:

  • Missing API key
  • Invalid API key
  • Provider unavailable
  • Rate limit
  • No package.json found
  • Unsupported project structure
  • Corrupt snapshot
  • Missing snapshot
  • Permission errors
  • Node version too old

20. Cross-Platform Testing Strategy

DevMap must work across:

  • Windows
  • macOS
  • Linux

Minimum Local Testing

Before first publish:

  • Windows local machine
  • At least one non-Windows environment through GitHub Actions

GitHub Actions Matrix

Future CI should test:

  • OS: Windows, Ubuntu, macOS
  • Node: 18, 20, 22

Windows-Specific Rules

  • Use path.join() and path.resolve()
  • Never hardcode /
  • Handle CRLF and LF line endings
  • Do not rely on Unix-only executable permissions
  • Avoid shell commands that only work on Bash

21. Future Commands

Roadmap

Command Phase Priority
devmap onboarding MVP 0.1.0 candidate High
devmap docs Phase 3 Medium
devmap flow Phase 4 Medium
devmap trace Phase 4 Medium
devmap report Phase 4 Low
devmap deadcode Phase 4 Low
devmap watch Future Later
devmap visual Future Later

devmap onboarding (MVP 0.1.0 Candidate)

Purpose: developer productivity accelerator.

Core question it answers:

Where should I start?

Output sections:

  1. Project Summary
  2. First Files To Read
  3. Recommended Learning Path
  4. Feature Map
  5. Modification Guide
  6. Entry Points
  7. Contribution Guide
  8. Estimated Understanding Time

devmap docs (Phase 3)

Generate project documentation artifacts.

Output:

docs/
├── project-overview.md
├── architecture.md
├── onboarding.md
├── api.md
└── flow.md

devmap docs generates documentation artifacts.
devmap onboarding generates a learning/productivity guide from the current snapshot. devmap onboard remains a shorthand alias.

These are related but not the same.

devmap flow (Phase 4)

Generate flow explanation.

Output:

  • User flow
  • API flow
  • Data flow
  • Service flow
  • Mermaid diagram

devmap trace (Phase 4)

Trace how files, functions, or features are connected.

Usage:

devmap trace createWorkspace
devmap trace auth.ts
devmap trace "booking flow"

Output example:

createWorkspace

Called By:
  - CreateWorkspaceModal.tsx
  - app/api/workspaces/route.ts

Uses:
  - workspace.service.ts
  - prisma.workspace.create()

Related Feature:
  Workspace Management

22. Future AI Modes

Cloud Mode (Phase 5)

Additional providers:

  • OpenAI
  • Gemini

Local Mode (Future)

Powered by Ollama.

Purpose:

  • Privacy
  • Offline usage
  • Unlimited local inference
  • No API key required

Potential models:

  • Qwen3 8B
  • Qwen2.5-Coder 7B
  • DeepSeek R1 8B

Before setup, DevMap must show:

  • Model size and download size
  • RAM requirement
  • Estimated download duration
  • Expected performance vs cloud

Local Mode must never silently download large models.

Hybrid Mode (Future — after Cloud + Local are stable)

Combine local + cloud model for lower token usage, better privacy, and improved reasoning when needed.

23. Repository Structure

DevMap uses a pnpm monorepo.

devmap/
├── LICENSE
├── README.md
├── PRD.md
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
│
├── docs/
│   ├── architecture.md
│   ├── roadmap.md
│   ├── commands.md
│   ├── user-persona.md
│   └── terminal-design.md
│
└── packages/
    └── cli/
        ├── package.json
        └── src/
            ├── commands/
            ├── analyzer/
            ├── scanner/
            ├── ai/
            │   ├── ai-client.ts
            │   ├── providers/
            │   ├── context-builder.ts
            │   └── prompts.ts
            ├── config/
            ├── output/
            ├── types/
            ├── utils/
            └── index.ts

Landing page/web can be added later under apps/web, but must not distract from CLI MVP.

24. Success Metrics

Launch — Month 1

  • 10+ developers besides myself install and run devmap analyze
  • 3+ unprompted feedback saying "this is useful"
  • Zero crashes on the happy path

Early Traction — Month 3

  • 100+ GitHub stars
  • Someone shares DevMap on Twitter/Reddit without being asked
  • At least 1 bug report from a real user

Validation — Month 6

  • A developer depends on DevMap for their workflow
  • At least 1 person requests a specific feature
  • Someone contributes a PR or opens a meaningful issue

25. Risks & Mitigations

Risk Mitigation
Static analysis inaccurate on unconventional projects Keep MVP detection scoped to tested Next.js, Express, and standalone React signals
User frustrated by API key setup devmap init wizard is fully guided
AI output misleading Frame output as overview, not absolute ground truth
Windows / Mac / Linux inconsistency Test with GitHub Actions matrix
Scope creep during development Re-read this PRD before adding anything new
DevMap seen as weaker Claude Code Position as project map/context layer
Token usage too high Static analysis first, compact context, snapshot reuse
Local AI onboarding too heavy Local Mode is future only and requires clear warnings
Context builder selects wrong files Start with heuristics, manually validate, improve later
Snapshot schema changes too often Version schema from the start
User dislikes AGENTS.md modification Ask before appending; never overwrite

26. Launch Checklist

DevMap is ready to publish when all of these are true:

Core Commands

  • devmap init runs without crashing
  • devmap analyze runs without crashing on a Next.js project
  • devmap analyze runs without crashing on an Express project
  • devmap doctor returns useful diagnostic output

Quality

  • Snapshot schema is documented and versioned
  • All major error scenarios handled
  • No raw stack traces exposed on normal failure
  • Caching/snapshot works correctly
  • Context Builder tested on at least 20 benchmark questions

Distribution

  • README written with demo GIF
  • npm package README and metadata are release-ready
  • Changelog and release process are documented
  • npm pack and install from packed file succeeds
  • npx devmap works without global install

Project Setup

  • .devmap/ automatically added to .gitignore on init
  • DEVMAP.md generated on init
  • Existing AGENTS.md is never overwritten
  • Existing AGENTS.md append requires confirmation

Testing

  • Tested on at least 3 different real projects
  • Tested on Windows
  • Tested on non-Windows environments through CI
  • Live Groq flow tested by the maintainer

Post-Launch Beta Validation

These do not block the 0.1.0 early beta publish:

  • At least one person besides the maintainer has tried it and given feedback
  • Raw-file vs snapshot benchmark tested using Groq usage data
  • Benchmark results recorded
  • Public token-efficiency claims adjusted based on evidence

Until those checks are complete, public copy must describe DevMap as designed to reduce repeated exploration rather than claiming measured token savings.

27. License

MIT License

Reasons:

  • Friendly for open source adoption
  • Easy for contributors
  • Maximizes reach and distribution

Last updated: June 2026
Maintained by: Fadil (@itsflaid)