Skip to content

generated-files.md

Latest commit

 

History

History
273 lines (187 loc) · 4.62 KB

generated-files.md

File metadata and controls

273 lines (187 loc) · 4.62 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

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.