LLM Project Mapper

🇺🇸 English. Leia em português: README.pt-BR.md.

AI-friendly, stack-neutral repository scaffold. Drop it into any project — new or existing — and any agent CLI (Claude Code, Codex, Cursor, GitHub Copilot, Aider with Deepseek/Kimi/MiniMax/GLM, Hermes, OpenClaw) gets the context it needs to ship work the same day.

Starter pack, not a framework. Ships structure, instructions, process. Stack is yours.

Visual summary: drop the starter into a messy software project and it turns scattered context into structure, reusable skills, tests, docs, and guardrails for AI coding agents.

Watch: why llm-project-mapper? (53s)

Click the cover to play. Direct link: video/assets/why-llm-project-mapper.mp4 · English version: video/assets/why-llm-project-mapper-en.mp4.

Operational Docs For Agents

This starter now includes generic, fill-in templates that make any project easier for agents to operate:

• docs/local-setup.md: how to install, start, validate and access the project.
• docs/domain-map.md: business concepts, critical rules and edge cases.
• docs/architecture-map.md: system shape, request path and integrations.
• docs/features/README.md: feature documentation template with files, endpoints, rules and evidence.
• docs/evidence/README.md: screenshot/video/trace policy and artifact naming.
• docs/troubleshooting.md: repeatable diagnosis and fixes.
• scripts/: stack-neutral placeholders for start, test and evidence commands.
• tests/e2e/smoke.spec.ts: generic Playwright smoke test driven by BASE_URL.

Fill these files after installing the starter in a real project. The goal is to reduce discovery time for humans and agents without forcing a framework.

TL;DR — get going in 60 seconds

Pick one of the install paths below, run it inside your project folder, then let the agent run INIT.md.

Same command everywhere. No bash dependency, no clone, no global install.

What LLM Project Mapper Changes

The point of the starter is not “more files”. It is faster agent execution with less ambiguity, less tribal knowledge, and safer delivery loops.

01 · From project chaos to operational structure

Drop the starter into an existing codebase and it converts scattered context into repeatable docs, validation, agent instructions, and delivery guardrails.

02 · Shared context for parallel agents

Agents stop working as isolated chat sessions and start collaborating around the same project map: architecture, tasks, checks, and output expectations.

03 · A stable foundation for safe speed

The end state is an agent-ready project foundation: domain context, architecture, workflow, quality gates, and evidence paths that make automation reliable instead of risky.

Prerequisites

Pick one runtime: npx works everywhere; bootstrap.sh for Unix shells; bootstrap.ps1 for native Windows.

What it ships

your-project/
├── AGENTS.md                 # master agent instructions (read by every CLI)
├── CLAUDE.md                 # mirror of AGENTS.md (Claude Code)
├── INIT.md                   # one-shot prompt the agent runs after bootstrap
├── .github/
│   ├── copilot-instructions.md    # mirror of AGENTS.md (Copilot)
│   ├── workflows/                  # CI + Definition-of-Done gate
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── ISSUE_TEMPLATE/
├── .specs/                   # canonical docs (specs as code)
│   ├── product/              # VISION, DOMAIN, PERSONAS
│   ├── architecture/         # DESIGN, PATTERNS, ADRs
│   ├── workflow/             # WORKFLOW, CONTRIBUTING, RELEASE
│   └── sprints/              # BACKLOG + sprint folders
├── .skills/                  # reusable agent skills
├── .agents/                  # custom sub-agents
├── .claude/                  # Claude Code config + hooks
├── .codex/                   # Codex CLI config
├── playwright.config.ts      # default E2E
└── presentation/             # method slides (Marp)

Stack-neutral: anything specific to your stack gets filled by INIT.md when the agent inspects the real code.

Install paths

A. npx — recommended, cross-platform, zero clone

# inside your project folder (works on macOS, Linux, Windows)
npx @wesleysimplicio/llm-project-mapper

Runs interactively. Asks only:

1. Which CLI/LLM to hand off to (auto-detects which ones are installed and marks them [installed]).
2. Append recommended ignores to .gitignore? (yes/no — never overwrites your existing .gitignore).

Everything else — PRODUCT_NAME, stack, dependencies — auto-detected from package.json / pyproject.toml / go.mod / *.csproj / Cargo.toml / pubspec.yaml / composer.json / Gemfile / mix.exs / pom.xml / build.gradle*.

Non-interactive (CI / scripts)

npx @wesleysimplicio/llm-project-mapper --yes --cli skip --append-gitignore no

Update an existing starter overlay

npx @wesleysimplicio/llm-project-mapper@latest --update

This is equivalent to --yes --force --append-gitignore yes --cli skip: it refreshes starter-managed files, updates the starter .gitignore block, preserves existing instruction files, and does not launch an agent.

Preview without writing

npx @wesleysimplicio/llm-project-mapper --dry-run --yes

Full flag list

B. bootstrap.sh — Unix shells (macOS / Linux / Git Bash / WSL)

Clone the starter and run the script:

git clone --depth=1 https://github.com/wesleysimplicio/llm-project-mapper.git tmp-starter
cp -R tmp-starter/. ./ && rm -rf tmp-starter
chmod +x ./bootstrap.sh   # only the first time
./bootstrap.sh

C. bootstrap.ps1 — native Windows (PowerShell)

git clone --depth=1 https://github.com/wesleysimplicio/llm-project-mapper.git tmp-starter
Copy-Item -Recurse -Force tmp-starter\* .\
Remove-Item -Recurse -Force tmp-starter

# PowerShell 7+ (pwsh)
pwsh -File .\bootstrap.ps1

# PowerShell 5.1 (built-in on Windows 10/11)
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1

All three paths produce the same result and ask the same two questions.

D. Overlay onto an existing project (private, gitignored)

Want to drop the starter into a project that already has its own git, without polluting the host repo? Each dev installs locally, files stay gitignored. Full step-by-step in INSTALL.md. Short version:

# from inside the host project root
git clone --depth=1 https://github.com/wesleysimplicio/llm-project-mapper.git /tmp/llm-project-mapper-src
# --ignore-existing protects your host's package.json/README.md/etc from being overwritten
rsync -av --ignore-existing --exclude='.git' /tmp/llm-project-mapper-src/ ./
rm -rf /tmp/llm-project-mapper-src
# append the "LLM Project Mapper (overlay privado)" block from INSTALL.md to your .gitignore FIRST
# then run bootstrap
./bootstrap.sh

CLI handoff — supported agents

After scaffolding, the bootstrap asks which CLI/LLM to launch with INIT.md. Detected installs get a [installed] mark in the menu.

For Copilot CLI (no native agent loop), the bootstrap copies the prompt to your clipboard (pbcopy on macOS, xclip/wl-copy on Linux, clip.exe on Windows/WSL) and you paste it into Copilot Chat.

What INIT.md does — the safety contract

When the chosen CLI runs INIT.md, it reads .starter-meta.json and follows three hard rules:

1. read_only_globs are intouchable. Any file matching these globs (**/*.razor, **/*.cs, **/*.csproj, **/*.sln, package.json, pnpm-lock.yaml, yarn.lock, package-lock.json, **/*.py, **/*.go, **/*.rs, **/*.java, **/*.kt, **/*.dart, **/*.php, **/*.rb) is read-only. The agent reads it for context but never writes. If git status shows any after init — that is a bug.
2. init_must_merge preserves your essence. If AGENTS.md / CLAUDE.md / .github/copilot-instructions.md already existed before bootstrap, the agent reads them, preserves the content, and merges the starter structure on top. Never a clean rewrite.
3. init_must_ask only asks 4 things. team, domain, vision_oneliner, primary_personas — once, in a single message. Everything else (product_name, stack) is auto-detected.

The agent then writes — and only writes — inside the whitelist:

.specs/**          .agents/**         .skills/**
.claude/**         .codex/**
.github/copilot-instructions.md
.github/copilot/**
.github/PULL_REQUEST_TEMPLATE.md
.github/ISSUE_TEMPLATE/**
.github/workflows/ci.yml
.github/workflows/dod.yml
AGENTS.md  CLAUDE.md  README.md  README.pt-BR.md
playwright.config.ts (only if missing or our template)

Anything outside this whitelist and not from the starter template = untouched.

Troubleshooting

macOS / Linux

Windows

Cross-platform

Suggested reading order (human)

1. README.md (this file) — overview.
2. AGENTS.md — agent master instruction.
3. .specs/README.md — specs navigation map.
4. .specs/product/VISION.md — product context.
5. .specs/architecture/DESIGN.md — architecture.
6. .specs/workflow/WORKFLOW.md — process.
7. .skills/README.md — agent capabilities.

Quickstart for the agent (after INIT.md)

1. Read AGENTS.md (root). That is the contract.
2. Read .specs/product/VISION.md for the why.
3. Read .specs/architecture/DESIGN.md and PATTERNS.md for the how.
4. Pull the next task from .specs/sprints/sprint-XX/.
5. Run the mandatory loop: read task → plan → edit → lint → unit → e2e → fix → commit.
6. Validate Definition of Done before opening a PR.

Optional: clean up starter files

After the agent finishes INIT.md, the bootstrap files are no longer needed.

macOS / Linux / Git Bash / WSL:

rm _BOOTSTRAP.md INIT.md bootstrap.sh bootstrap.ps1
git add -A && git commit -m "chore: remove starter bootstrap files"

Windows PowerShell:

Remove-Item _BOOTSTRAP.md, INIT.md, bootstrap.sh, bootstrap.ps1
git add -A; git commit -m "chore: remove starter bootstrap files"

.starter-meta.json stays as a reference for future re-runs.

Philosophy

• Specs as code. What is not in .specs/, the agent does not see.
• Atomic tasks. One task = one small reviewable PR.
• Automated DoD. What does not pass the gate, does not merge.
• Reusable skills. A capability that becomes a pattern becomes a SKILL.md.
• Tight loop. Edit, test, fix, repeat. Never accumulate invisible debt.
• Never destroy. User files are read-only; starter files merge instead of overwrite.

License

MIT © 2026 Wesley Simplicio.

Next steps

• Run the bootstrap.
• Let the agent execute INIT.md.
• Fill specs with real product context (the agent does most of this from the code).
• Run the first sprint using .specs/sprints/sprint-01/.
• Watch presentation/ai-agent-specialist.pdf for the full method.