Skip to content

Commit e21869b

Browse files
LanternCXLanternCX
committed
feat(agents): add AGENTS.md and progress System
1 parent 382b83b commit e21869b

4 files changed

Lines changed: 235 additions & 0 deletions

File tree

‎.progress/PROGRESS.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Progress Memory
2+
3+
Project-level progress index and reusable implementation notes.
4+
5+
## Entry Template
6+
7+
Use this template for new entries in `.progress/entries/<YYYY>/`:
8+
9+
```markdown
10+
# YYYY-MM-DD-N
11+
12+
## Date
13+
YYYY-MM-DD
14+
15+
## Title
16+
[Short actionable title]
17+
18+
## Background / Issue
19+
[Context, trigger, constraints]
20+
21+
## Actions / Outcome
22+
- Approach 1: [what was tried] -> [result]
23+
- Approach 2: [what was tried] -> [result]
24+
- Final approach: [adopted approach] -> [why it worked]
25+
26+
## Lessons / Refinements
27+
- [Reusable pattern]
28+
- [Avoidance note]
29+
30+
## Related Commit Message
31+
type(scope): summary
32+
33+
## Related Commit Hash
34+
abc123d (or TBD)
35+
```
36+
37+
## Global TOC
38+
39+
| Page ID | Date | Title | Path | Keywords |
40+
| --- | --- | --- | --- | --- |
41+
| 2026-03-03-1 | 2026-03-03 | Stabilized full deploy flow and improved onboarding UX | `.progress/entries/2026/2026-03-03-1.md` | deploy, mpremote, config-wizard, docs |

‎.progress/entries/2026/.gitkeep‎

Whitespace-only changes.

‎.progress/entries/2026/2026-03-03-1.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# 2026-03-03-1
2+
3+
## Date
4+
2026-03-03
5+
6+
## Title
7+
Stabilized full deploy flow and improved onboarding UX
8+
9+
## Background / Issue
10+
Full-mode flashing initially failed on the RT1021 board due to raw REPL entry errors and wipe behavior mismatches on mounted filesystems. In parallel, first-time user onboarding still depended on manual config edits and incomplete CLI parameter documentation.
11+
12+
## Actions / Outcome
13+
- Approach 1: Reproduced failures with real board + non-interactive deploy command -> confirmed `could not enter raw repl` and wipe failure paths.
14+
- Approach 2: Switched backend commands to `mpremote connect <port> resume ...`, fixed wipe script to clean `/flash` contents safely, and created remote parent directories before nested uploads -> full deploy completed with `success=93 failure=0`.
15+
- Approach 3: Added interactive config wizard (`init` + `config`), port auto-scan selection, per-operation deploy logging, and README parameter completeness checks -> onboarding became command-driven and test-covered.
16+
- Final approach: Combined reliability fixes + UX improvements + regression tests -> achieved stable flashing and maintainable CLI behavior under automated verification.
17+
18+
## Lessons / Refinements
19+
- Hardware-facing CLI tooling should validate behavior on real devices, not only mocked command assembly.
20+
- For nested device uploads, creating remote parents proactively is safer than relying on backend command defaults.
21+
- Docs drift can be reduced by adding explicit test assertions for required command/parameter coverage.
22+
23+
## Related Commit Message
24+
feat(cli): improve deploy reliability and interactive setup
25+
26+
## Related Commit Hash
27+
8f67ddb (follow-up: 382b83b)

‎AGENTS.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# AGENTS Guide (`mpy-cli`)
2+
3+
This guide is for coding agents working in this repository.
4+
Follow these commands and conventions unless the user explicitly asks otherwise.
5+
6+
## Scope
7+
- Applies to the whole repo.
8+
- Main language: Python.
9+
- Main function: deploy local code to MicroPython devices via `mpremote`.
10+
11+
## External Agent Rules
12+
- Cursor rules dir: `.cursor/rules/` -> not present.
13+
- Cursor single file rules: `.cursorrules` -> not present.
14+
- Copilot instructions: `.github/copilot-instructions.md` -> not present.
15+
- If any of these files are added, treat them as higher-priority local instructions.
16+
17+
## Repository Facts
18+
- Python: `>=3.10` (3.11 recommended).
19+
- Packaging/config: `pyproject.toml`.
20+
- CLI entrypoint: `mpy_cli.cli:main`.
21+
- Console script: `mpy-cli`.
22+
- Tests: `pytest`, under `tests/`.
23+
- CI release workflow: `.github/workflows/release.yml`.
24+
25+
## Setup Commands
26+
Run from repo root:
27+
28+
```bash
29+
python3 -m venv .venv
30+
source .venv/bin/activate
31+
python3 -m pip install --upgrade pip
32+
python3 -m pip install -e ".[dev]"
33+
```
34+
35+
## Build / Lint / Test Commands
36+
No dedicated formatter/linter is configured in `pyproject.toml`.
37+
Testing is the primary quality gate.
38+
39+
### Install / package actions
40+
```bash
41+
# editable install for development
42+
python3 -m pip install -e ".[dev]"
43+
44+
# non-editable install
45+
python3 -m pip install .
46+
```
47+
48+
### Run all tests
49+
```bash
50+
python3 -m pytest -q
51+
```
52+
53+
### Run one test file
54+
```bash
55+
python3 -m pytest -q tests/test_cli.py
56+
```
57+
58+
### Run one test case (important)
59+
```bash
60+
python3 -m pytest -q tests/test_cli.py::test_init_command_creates_config_and_ignore
61+
```
62+
63+
### Run by keyword
64+
```bash
65+
python3 -m pytest -q -k config
66+
```
67+
68+
### Useful targeted suites
69+
```bash
70+
python3 -m pytest -q tests/test_docs_and_ci.py
71+
python3 -m pytest -q tests/test_mpremote_backend.py
72+
python3 -m pytest -q tests/test_executor.py
73+
```
74+
75+
### Optional syntax sanity check
76+
```bash
77+
python3 -m compileall mpy_cli
78+
```
79+
80+
## CLI Smoke Commands
81+
```bash
82+
mpy-cli init
83+
mpy-cli config
84+
mpy-cli plan --mode incremental --port /dev/ttyACM0
85+
mpy-cli deploy --mode incremental --port /dev/ttyACM0
86+
```
87+
88+
Non-interactive examples:
89+
```bash
90+
mpy-cli plan --mode full --no-interactive --port /dev/ttyACM0
91+
mpy-cli deploy --mode full --no-interactive --yes --port /dev/ttyACM0
92+
```
93+
94+
## Code Style Guidelines
95+
96+
### Imports
97+
- Order imports: stdlib -> third-party -> local.
98+
- Prefer explicit imports; avoid wildcard imports.
99+
100+
### Formatting
101+
- Use 4-space indentation.
102+
- Keep long calls split across lines for readability.
103+
- Keep diffs stable (use trailing commas in multiline literals/calls when helpful).
104+
105+
### Types
106+
- Add type hints for public functions/methods.
107+
- Type dataclass fields explicitly.
108+
- Use `Literal` for constrained string values (`full`, `incremental`).
109+
- Use `Protocol` for pluggable interfaces (e.g., logger/scanner contracts).
110+
111+
### Naming
112+
- `snake_case`: functions, vars, modules.
113+
- `PascalCase`: classes/dataclasses.
114+
- `UPPER_CASE`: constants.
115+
- Errors should end with `Error`.
116+
117+
### Docstrings and Comments
118+
- Follow existing convention: Chinese Doxygen-style docstrings.
119+
- Public APIs should include `@brief`; add `@param`/`@return` when useful.
120+
- Add comments only for non-obvious logic.
121+
122+
### Error Handling
123+
- Raise domain-specific exceptions in lower layers:
124+
- `ConfigError`
125+
- `GitDiffError`
126+
- `CommandExecutionError`
127+
- At CLI boundaries, convert expected failures to readable messages + exit codes.
128+
- Avoid exposing raw traceback to end users for expected errors.
129+
130+
### Logging
131+
- Use `setup_logging()` from `mpy_cli/logging.py`.
132+
- Keep dual output: console + rotating file logs.
133+
- Preserve deploy progress logs (per operation / per file).
134+
135+
### Paths and Persistence
136+
- Prefer `pathlib.Path`.
137+
- Keep runtime artifacts under project runtime dir (default `.mpy-cli/`).
138+
- Do not write runtime artifacts to system directories.
139+
140+
### CLI Behavior Rules
141+
- Keep parser behavior, README examples, and tests synchronized.
142+
- If CLI args change, update all three:
143+
1) `mpy_cli/cli.py`
144+
2) `README.md` parameter section
145+
3) `tests/test_docs_and_ci.py`
146+
147+
### Deployment Semantics
148+
- `full`: wipe then upload all allowed files.
149+
- `incremental`: compute operations from git changes.
150+
- Nested uploads must ensure remote parent directories exist first.
151+
152+
## Test Writing Conventions
153+
- Test files: `tests/test_*.py`.
154+
- Test names: `test_<behavior>`.
155+
- Keep tests behavior-focused and deterministic.
156+
- Add regression tests for every bug fix.
157+
158+
## Documentation Conventions
159+
- Keep command examples in `README.md` current.
160+
- Keep parameter lists complete when CLI flags change.
161+
- Keep `docs/developer-guide.md` aligned with architecture changes.
162+
163+
## Agent Completion Checklist
164+
1. Run targeted tests for changed modules.
165+
2. Run full suite: `python3 -m pytest -q`.
166+
3. Verify README command examples still match real CLI behavior.
167+
4. Ensure local artifacts are not accidentally staged.

0 commit comments

Comments
 (0)