Skip to content

generated-files.md

Latest commit

 

History

History
301 lines (205 loc) · 5.49 KB

generated-files.md

File metadata and controls

301 lines (205 loc) · 5.49 KB
Raw

Generated Files

DEVMAP.md

Generated during:

devmap init

Purpose:

  • Human instructions
  • AI instructions
  • Explain DevMap workflow

AGENTS.md

Generated or updated during:

devmap init

Purpose:

Direct AI agents to DevMap.

Generated DEVMAP.md tells AI agents to use command-level --json output instead of parsing decorated terminal text. This applies to analyze and doctor, while init --json is intended for non-interactive setup with an environment API key.

Its navigation contract uses this order:

  1. .devmap/index.json
  2. the relevant .devmap/features/*.json map
  3. files listed in sourcePriority
  4. .devmap/snapshot.json only when the lightweight maps are insufficient

Rules:

  • Never overwrite existing file
  • Create a basic file when AGENTS.md does not exist
  • Ask before appending to an existing regular file
  • Append only the small DevMap instruction block
  • Skip an existing file in non-interactive mode
  • Do not append the block more than once
  • Refuse to update a symlinked AGENTS.md

Confirmation:

AGENTS.md exists. Append DevMap instructions? [y/N]:

Only y or yes appends the block. Any other answer preserves the existing file unchanged.

.devmap/index.json

Generated during:

devmap analyze

Purpose:

Primary machine-readable entry point for AI coding agents.

Contains:

  • Project identity
  • Entry points
  • Critical files
  • Feature navigation
  • Lightweight project metadata

This file intentionally stays compact and points AI toward .devmap/features/*.json before falling back to the full snapshot.

.devmap/features/*.json

Generated during:

devmap analyze

One file is generated for every detected feature.

Example:

.devmap/
└── features/
    ├── authentication.json
    ├── workspace.json
    └── snippet-management.json

Purpose:

  • Feature summary
  • Entry points
  • Related files
  • File roles
  • Keywords
  • Confidence
  • Source priority

Acts as the bridge between index.json and the full snapshot.

.devmap/snapshot.json

Generated during:

devmap analyze

Purpose:

  • Source of truth
  • Full reusable project snapshot
  • AI context archive
  • Debugging information

Regenerated whenever the project changes or when:

devmap analyze --fresh

is executed.

The snapshot intentionally does not contain full source code.

DevMap generates the following files when you run its commands.

.devmap/maps/

Generated by:

devmap map

Example:

.devmap/
└── maps/
    ├── project.md
    ├── project.mmd
    ├── authentication.md
    ├── authentication.mmd
    └── workspace.md

Purpose:

  • Project relationship maps
  • Feature maps
  • Mermaid diagrams
  • Human-readable architecture overview

.devmap/flows/

Generated by:

devmap flow
devmap flow --all   # uncapped: medium-confidence features + non-API routes

Example:

.devmap/
└── flows/
    ├── authentication.md
    ├── authentication.mermaid
    ├── request-login.md
    ├── request-login.mermaid
    └── snippet-management-flow.md
    └── snippet-management-flow.mermaid

Purpose:

  • Execution flow documentation
  • Request lifecycle
  • Feature flows
  • Mermaid flow diagrams

Notes:

  • One .md + one .mermaid file per flow.
  • Default output uses the curated flows already computed by devmap analyze; --all rebuilds a larger set from the snapshot without re-scanning.
  • With a configured API key, each flow's static step list is enriched with a short AI narration paragraph (flowNarration); otherwise the step list is used as-is.

ONBOARDING.md

Generated by:

devmap onboarding --write

Written to the project root (ONBOARDING.md), not inside .devmap/.

Purpose:

  • Project overview
  • Recommended reading order
  • Architecture summary
  • Important entry points
  • Quick onboarding guide for new developers

.devmap/analyze.lock

Created while devmap mcp runs an analysis (devmap_analyze or --auto-refresh) and removed when it finishes.

{ "pid": 12345, "startedAt": "2026-10-30T02:11:09.000Z" }

Purpose:

  • Stop two MCP servers (or editor windows) from writing the snapshot at once

A lock whose process is gone, or that is older than 15 minutes, is taken over automatically. If no analysis is running and the file is still there, it is safe to delete. devmap analyze does not create or check this file.

Like the rest of .devmap/, it is gitignored.

What the MCP server writes

devmap mcp answers from the files above and writes nothing unless an analysis runs. devmap_map, devmap_flow and devmap_explain never write .devmap/maps/, .devmap/flows/ or .devmap/explain/; those folders are only created by the CLI commands. See mcp.md.

Next Phase — Not Generated Yet

The following files are planned for future phases.

.devmap/agent/

Phase 5 — Agent Layer

Reserved for DevMap Agent runtime data.

Example:

.devmap/
└── agent/
    ├── context.json
    ├── state.json
    ├── cache.json
    └── history.json

Purpose:

  • Working context
  • Incremental project updates
  • Smart cache
  • Agent runtime state

This directory is intentionally separate from snapshot.json.

snapshot.json remains the immutable source of truth generated by devmap analyze, while .devmap/agent/ stores temporary runtime data used by future DevMap Agent features.