615d4a6115
- Add docs/plans/README.md as the roadmap index cataloguing all design/plan docs. - Add the custom ISO14443-A command handling design + plan (L3 NTAG I2C SECTOR_SELECT / cross-sector reads + native auth; L4 static APDUs + WTX relay), produced from a multi-agent design workflow. - Backfill previously-uncommitted plan docs (trace-formatter, ndef-trace-decode, live-sniff, firmware-upstream-rebase, 14a-live-trace) and NTAG5_SECURITY.md. - Sync CLAUDE.md package structure with the committed transponder models. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
pm3py roadmap — design & implementation plans
This directory is the project roadmap: dated design docs (*-design.md) and
implementation plans (*-plan.md). Each file is a self-contained spec — problem,
approach, concrete steps, tests, risks.
Status column is best-effort, inferred from the codebase and memory at the time of writing (2026-07-05). Correct it if a plan's real state differs. Legend: ✅ landed · 🔄 in progress · 📋 planned · 📎 reference/ongoing.
ISO 14443-A sim expansion
| Plan | Status | Summary |
|---|---|---|
| 2026-07-05-14a-live-trace-plan | 🔄 | Live reader↔tag trace for the 14a sim (firmware ring + EmLogTrace capture + pm3py consumer). Code complete; flush + direct-send-capture fixes awaiting hardware verify. |
| 2026-07-05-14a-custom-commands-design | 📋 | Design: how to serve custom 14a-3 (NTAG I2C SECTOR_SELECT + cross-sector reads) and 14a-4 (vendor ISO-DEP APDUs) commands — table-first L3 + WTX-L4 hybrid layered on the native-EML sim. |
| 2026-07-05-14a-custom-commands-plan | 📋 | Plan: sequenced L3 + L4 tracks — sim_table hook, sector-offset graft, WTX relay, TableCompiler extension, tests. |
Sim framework & response table
| Plan | Status | Summary |
|---|---|---|
| 2026-03-17-stateful-table-firmware-design | ✅ | Response-table sim in firmware BigBuf: stateful sim_table + sim_crypto, group/auth state. |
| 2026-03-17-stateful-table-firmware-plan | ✅ | Implementation of the above (15693 sim fully working: inventory, NDEF, NXP custom commands). |
| 2026-03-17-table-compiler-update-plan | ✅ | TableCompiler / ResponseTable — compile per-IC responses into the 120-byte entry format. |
Trace & sniff
| Plan | Status | Summary |
|---|---|---|
| 2026-03-17-trace-formatter-design | ✅ | TraceFormatter — colored, decoded, column-wrapped trace output (sim/reader/sniff modes). |
| 2026-03-17-trace-formatter-plan | ✅ | Implementation of the trace formatter. |
| 2026-03-18-ndef-trace-decode | ✅ | NDEF TLV/record decode for trace annotation. |
| 2026-03-19-live-sniff-design | ✅ | Live streaming sniff (firmware CMD_HF_SNIFF_STREAM + SniffSession). |
| 2026-03-19-live-sniff-plan | ✅ | Implementation of live sniff. |
Package refactor & migration
| Plan | Status | Summary |
|---|---|---|
| 2026-03-18-refactor-design | ✅ | Split the monolith into core/, trace/, sniff/, sim/, transponders/. |
| 2026-03-18-refactor-progress | ✅ | Progress log for the refactor (complete, all on master). |
| 2026-03-18-sim-migration | ✅ | Migrate the sim framework into the new package layout. |
Firmware maintenance
| Plan | Status | Summary |
|---|---|---|
| 2026-07-03-firmware-upstream-rebase-plan | 📎 | Rebase the proxmark3-pm3py fork against upstream PM3 (atomic single-file-commit workflow). |
Conventions
- Naming:
YYYY-MM-DD-<topic>-{design,plan}.md. A design doc explains why and what; a plan doc gives sequenced, implementation-grade steps. Small features may have only a-plan.md. - Firmware changes land as atomic single-file commits anchored to stable symbols (not line numbers) for easy rebase against upstream — see the firmware-upstream-rebase plan.
- Provenance: plans produced with multi-agent design workflows note it in a Provenance section.