From 63c6864868b10e659c64db86d253627d7a18a013 Mon Sep 17 00:00:00 2001 From: Patrick Skillen Date: Wed, 3 Jun 2026 09:03:15 +0100 Subject: [PATCH] chore: move Cursor skills/rules to MeshFlow umbrella Skills (meshflow-git-workflow, mf-feature-docs, progress-tracking) and rules (django-dont-install-stuff, mf-feature-docs) are now consolidated in the MeshFlow umbrella workspace (~/IdeaProjects/MeshFlow/.cursor) to remove cross-repo duplication. Update AGENTS.md and meshcore docs references. --- .cursor/rules/django-dont-install-stuff.mdc | 6 - .cursor/rules/mf-feature-docs.mdc | 9 - .cursor/rules/mf-feature-docs/SKILL.md | 106 ----------- .cursor/skills/meshflow-git-workflow/SKILL.md | 156 --------------- .cursor/skills/progress-tracking/SKILL.md | 179 ------------------ AGENTS.md | 2 +- docs/features/meshcore/README.md | 2 +- 7 files changed, 2 insertions(+), 458 deletions(-) delete mode 100644 .cursor/rules/django-dont-install-stuff.mdc delete mode 100644 .cursor/rules/mf-feature-docs.mdc delete mode 100644 .cursor/rules/mf-feature-docs/SKILL.md delete mode 100644 .cursor/skills/meshflow-git-workflow/SKILL.md delete mode 100644 .cursor/skills/progress-tracking/SKILL.md diff --git a/.cursor/rules/django-dont-install-stuff.mdc b/.cursor/rules/django-dont-install-stuff.mdc deleted file mode 100644 index b8d8864d..00000000 --- a/.cursor/rules/django-dont-install-stuff.mdc +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -globs: -alwaysApply: false ---- -This is a Django Rest Framework API project. Don't install packages unless required, and check with me first. When modifying the API contract, unless explicitly instructed, check with me first. Remember to update the openapi.yaml file if changing the API contract. \ No newline at end of file diff --git a/.cursor/rules/mf-feature-docs.mdc b/.cursor/rules/mf-feature-docs.mdc deleted file mode 100644 index 221e41eb..00000000 --- a/.cursor/rules/mf-feature-docs.mdc +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: Feature documentation under docs/features/ — follow mf-feature-docs skill -globs: docs/features/**/* -alwaysApply: false ---- - -When creating or editing files under `docs/features/`, read and follow [.cursor/rules/mf-feature-docs/SKILL.md](mf-feature-docs/SKILL.md). - -For multi-step initiatives, also use [progress-tracking](.cursor/skills/progress-tracking/SKILL.md): maintain `*-progress.md` and `*-outstanding.md` in the feature folder; update before opening PRs. diff --git a/.cursor/rules/mf-feature-docs/SKILL.md b/.cursor/rules/mf-feature-docs/SKILL.md deleted file mode 100644 index 55d1755c..00000000 --- a/.cursor/rules/mf-feature-docs/SKILL.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: mf-feature-docs -description: >- - How Meshflow documents features under docs/features/. Use when adding or - updating feature docs, reverse-engineering behaviour for a ticket, or creating - progress/outstanding logs for an initiative. ---- - -# Meshflow feature documentation - -Canonical feature docs live under **`docs/features//`** in **meshflow-api** (even when UI or bot code participates). Cross-cutting concerns stay in -**`docs/`** root (`RECENCY.md`, `ENV_VARS.md`, `permissions/`, `API.md`, `openapi.yaml`). - -Read [progress-tracking](../../skills/progress-tracking/SKILL.md) when an initiative needs execution handoff files. - ---- - -## Folder layout - -| Pattern | When to use | Examples | -| --- | --- | --- | -| **`/README.md`** | Every feature area — hub page | `mesh-monitoring/README.md`, `packet-stats/README.md` | -| **Sibling deep dives** | One concern per file; keep README as map | `flow.md`, `permissions.md`, `meshtastic.md` | -| **`adr/`** | Irreversible or contested design choices | `packet-ingestion/adr/` | -| **`*-progress.md` / `*-outstanding.md`** | Multi-step plans, epics, or tickets spanning PRs | `phase-2-progress.md`, `packet-stats-progress.md` | -| **Phase files** | Large epics with numbered delivery | `meshcore/phase-1-progress.md` | - -**Slug:** kebab-case directory name matching the product concept (`packet-stats`, `mesh-monitoring`, not Django app name unless they align). - -**Do not** put the full plan backlog in `*-outstanding.md` — only debt discovered during execution (see progress-tracking skill). - ---- - -## README hub template - -Every feature README should open with **what problem it solves** (1–3 paragraphs), then: - -1. **Implementation status** — table: area | status | notes (shipped / in progress / deferred). -2. **Documentation map** — table linking sibling docs. -3. **Concepts** — domain terms the reader needs before detail pages. -4. **Optional diagram** — mermaid sequence/state when flow is non-obvious. -5. **Cross-links** — `RECENCY.md` for time windows, `openapi.yaml` tag for HTTP, related features, parent GitHub epic/issue. - -Stop at the feature boundary: ingestion README emits signals and points to downstream features; do not document traceroute completion inside packet-ingestion. - ---- - -## Deep-dive page template - -Use for `flow.md`, protocol-specific docs, etc. - -| Section | Contents | -| --- | --- | -| **Purpose** | What this slice does vs the hub README | -| **Code anchors** | Django app paths, main modules (`Meshflow/stats/tasks.py`) | -| **Data sources** | Models, fields, filters (be precise — contributors should not re-read code line-by-line) | -| **Schedules / env** | Celery beat, env vars with defaults; link `docs/RECENCY.md` § app | -| **HTTP API** | Paths, auth (`AllowGuestReadOnly` vs JWT), query params; point to OpenAPI | -| **Consumers** | meshflow-ui hooks/components, bots, ops commands | -| **Known gaps** | Explicit TODOs, deferred protocol support, doc drift | -| **Related** | Other feature docs, issues | - -Prefer **tables** for endpoints, snapshot types, and field shapes. Use **JSON examples** for `StatsSnapshot.value` and API payloads when shape matters. - ---- - -## Progress and outstanding pair - -Create both at **plan kickoff** if missing. Update **progress** when a PR/commit lands; update **outstanding** only for skipped scope or issues found while executing. - -| File | Role | -| --- | --- | -| `*-progress.md` | Shipped slices, PR links, branch, verify commands, **Next** | -| `*-outstanding.md` | Checkboxes for discovered debt — not future plan phases | - -Link both from the tracking GitHub issue and the Cursor plan **Progress tracking** section. - ---- - -## Style conventions (inferred from existing docs) - -- **British English** spelling in prose is fine; code identifiers stay as in repo. -- Link GitHub issues/PRs with full URLs: `[meshflow-api#329](https://github.com/pskillen/meshflow-api/issues/329)`. -- Use relative links between docs: `[meshtastic.md](meshtastic.md)`. -- Cite **concrete defaults** (e.g. “`:05` UTC”, “2 h window”) — they belong in feature docs *and* `RECENCY.md` for ops; feature doc explains *behaviour*, RECENCY is the quick index. -- When behaviour changes, update **feature doc**, **`RECENCY.md`** (if time-related), and **`openapi.yaml`** (if API contract changes). -- **Reverse-engineering ticket:** document *current* behaviour first in a protocol or mechanism doc; add `meshcore.md` (or a section) for planned parity before implementing. - ---- - -## Index maintenance - -When adding a new feature folder: - -1. Add a row or subsection under [docs/features/README.md](../../../docs/features/README.md) **Features** (or **Cross-Cutting** if appropriate). -2. Add `docs/RECENCY.md` § if the feature introduces recency windows or periodic jobs. -3. For MeshCore work, add a row to [docs/features/meshcore/README.md](../../../docs/features/meshcore/README.md) when relevant. - ---- - -## Anti-patterns - -- Duplicating `openapi.yaml` field lists in full — summarize and link OpenAPI. -- One giant README with no map (split when > ~200 lines or multiple audiences). -- Outstanding file copied from the Cursor plan todo list. -- Documenting aspirational behaviour as shipped — use **Implementation status** and **Known gaps**. diff --git a/.cursor/skills/meshflow-git-workflow/SKILL.md b/.cursor/skills/meshflow-git-workflow/SKILL.md deleted file mode 100644 index 81dcea21..00000000 --- a/.cursor/skills/meshflow-git-workflow/SKILL.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -name: meshflow-git-workflow -description: >- - Git workflow for Meshflow (meshflow-api, meshtastic-bot, meshtastic-bot-ui). - Plan with GitHub issues, branch by issue number, use conventional commits, - open PRs with linked tickets. Use when starting features, committing, or - opening pull requests in any Meshflow repo. ---- - -# Meshflow Git Workflow - -## Overview - -When working on a feature across meshflow-api, meshtastic-bot, or meshtastic-bot-ui, follow this workflow: plan → issue → branch → commit → PR. - -Use the `github-personal` MCP for all MeshFlow work. - -We start by documenting and refining a plan collaboratively. After agreeing upon the plan, create tickets in applicable repositories. If necessary add a parent ticket and create linked children. Add the plan to the single or parent ticket, and exerpts of the plan to any children. Update the plan with links to any relevant tickets. - -It's also possible that we start with a lightweight ticket (i.e. a feature request from a user), then generate the plan. In that situation, the ticket should be updated with full details from the plan, instead of creating a new one - -When executing the plan: - -1. Create our git branches from origin/main -2. Do the work -3. Commit as appropriate -4. Push and open a pull request for applicable repositories. Link relevant tickets. -5. Done - ---- - -## 1. Planning and Issues - -**Single-repo work**: Create one issue in the relevant repo with the plan. - -**Multi-repo work**: Create a parent issue in meshflow-api and child issues in each affected repo. Link children to the parent. - ---- - -## 2. Branch Naming - -Format: `{issue-repo-prefix}-{issue-number}/{author}/{short-description}` - -**Which prefix?** Use the prefix for the **GitHub repository where the tracking issue lives**, not the repo you are committing in. That keeps one issue number traceable across Meshflow repos. - -| Issue filed in | Prefix | Use that prefix in every repo that has a branch for the work | -|----------------|--------|----------------------------------------------------------------| -| meshtastic-bot-ui | `ui` | e.g. UI #136 → `ui-136/paddy/...` in **both** meshtastic-bot-ui **and** meshflow-api (and meshtastic-bot if needed) | -| meshflow-api | `api` | e.g. API #456 → `api-456/paddy/...` in every affected repo | -| meshtastic-bot | `bot` | e.g. bot #123 → `bot-123/paddy/...` in every affected repo | - -Use kebab-case for the description. Keep it short. - ---- - -## 3. Pre-commit Formatting - -**Before committing**, run the project's formatters: - -### meshflow-api - -```bash -cd meshflow-api -source venv/bin/activate -cd Meshflow -black . -isort . -flake8 . -``` - -### meshtastic-bot - -```bash -cd meshtastic-bot -source venv/bin/activate -black src/ -isort src/ -flake8 src/ -``` - -### meshtastic-bot-ui - -```bash -cd meshtastic-bot-ui -npm run format -``` - ---- - -## 4. Commits - -Use [conventional commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] -``` - -**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` - -**Rules**: -- Be brief but descriptive -- Do **not** use the word "enhance" - -**Examples**: -``` -feat(nodes): add last_heard filter to observed-nodes list -fix(api): correct timezone handling in packet ingestion -refactor(storage): extract packet parsing into service -``` - ---- - -## 5. Running git in Cursor agents - -When the agent **Shell** tool runs `git` (or other commands) in a Meshflow repo: - -1. **Always set `working_directory`** to the repository root (absolute path), e.g. `/Users/you/git_personal/meshflow-api`. Commands that only `cd` inside the command string often return **empty output** even when they succeed (exit code 0). - -2. **Good pattern** - - ```text - working_directory: /Users/you/git_personal/meshflow-api - command: git fetch origin && git status -sb - ``` - -3. **Permissions**: use `required_permissions: ["git_write"]` for checkout/commit; add `"network"` for `fetch` / `push`. - -4. **PRs and issues**: use the `github-personal` MCP. The `gh` CLI is not available on Meshflow dev machines. - -5. **Long pre-commit hooks**: meshflow-ui runs eslint + vitest on commit; use `block_until_ms` of 60–90s when committing there. - ---- - -## 6. Pull Requests - -When the work is done: - -1. Open a PR in each affected repository using the github-personal MCP. Do not use gh cli. -2. Link the relevant issue(s) in the PR (e.g. "Closes #123") -3. For multi-repo changes, link related PRs between repos in the description - -**PR description**: Use the project's `.github/pull_request_template.md` (Summary, Testing performed). - ---- - -## Quick Reference - -| Step | Action | -|------|--------| -| Plan | Issue in relevant repo(s); parent in meshflow-api if multi-repo | -| Branch | `{issue-repo-prefix}-{num}/{author}/{description}` (prefix = repo where the issue lives) | -| Pre-commit | meshflow-api/meshtastic-bot: venv + black, isort, flake8; meshtastic-bot-ui: `npm run format` | -| Commit | Conventional commits, no "enhance"; Shell `working_directory` = repo root | -| PR | Open in all affected repos, link issues and related PRs | diff --git a/.cursor/skills/progress-tracking/SKILL.md b/.cursor/skills/progress-tracking/SKILL.md deleted file mode 100644 index 01e855a8..00000000 --- a/.cursor/skills/progress-tracking/SKILL.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -name: progress-tracking -description: >- - Maintains progress and outstanding markdown logs for multi-step Meshflow plans - and epics. Use when executing a Cursor plan, a multi-repo feature, or when the - user asks to update progress/outstanding docs, hand off between agents, or - before opening a PR for a large initiative. ---- - -# Progress tracking (Meshflow plans) - -Persistent **progress** and **outstanding** files preserve execution state when context is lost, agents switch, or work spans multiple PRs. Follow this skill whenever a Cursor plan or epic has non-trivial scope (multi-commit, multi-repo, or high coordination risk). - -**Reference examples (large epic):** [docs/features/meshcore/phase-2-progress.md](../../docs/features/meshcore/phase-2-progress.md), [phase-2-outstanding.md](../../docs/features/meshcore/phase-2-outstanding.md). - ---- - -## Two files — distinct roles - -| File | Purpose | Put here | Do **not** put here | -|------|---------|----------|---------------------| -| **`*-progress.md`** | What **shipped** or is **in flight** | Merged PRs, deploy notes, verification commands, env vars, concrete file paths | Future plan steps not started; raw checklists copied from the plan | -| **`*-outstanding.md`** | **Debt discovered during execution** | Skipped scope, incomplete merges, bugs found, follow-ups that block verification, doc drift | The plan’s upcoming phases; epic backlog that was never in scope for this initiative | - -**Outstanding is not a second plan.** If work is scheduled but not started, it stays in the Cursor plan (or GitHub issue). Move an item to outstanding only when execution revealed it (missed, deferred mid-flight, or needs a later ticket). - ---- - -## Where files live - -Default under **`docs/features//`** in the repo that owns most of the work (usually **meshflow-api** for API-heavy initiatives). - -| Initiative | Progress | Outstanding | -|------------|----------|-------------| -| MeshCore phase epics | `phase-N-progress.md` | `phase-N-outstanding.md` | -| Focused plan (e.g. #362, enrollment) | `-progress.md` | `-outstanding.md` | - -**Slug:** kebab-case from the plan name (e.g. `managed-node-identity`, `enrollment`). - -For **multi-repo** work, one progress pair in meshflow-api is enough unless UI-only work needs `meshflow-ui/docs/...` (rare). Link sibling PRs from the api progress file. - -Add a row to [docs/features/meshcore/README.md](../../docs/features/meshcore/README.md) when the work is MeshCore-related. - ---- - -## When to read and update - -### At plan start (required) - -1. Read the linked **progress** and **outstanding** files if they exist. -2. If missing, create both from the templates below (initial progress = tracking issue, plan link, status **Not started** or **In progress**). -3. In the Cursor plan, add a **Progress tracking** section pointing at both files (see plan template). - -### During execution (at logical breakpoints) - -Update **progress** when: - -- A commit or PR lands a coherent slice (match [meshflow-git-workflow](../meshflow-git-workflow/SKILL.md) atomic commits). -- Deploy order or env prerequisites change. -- A phase flips to **Complete** with PR/issue links. - -Update **outstanding** when: - -- You skip or narrow scope and need a follow-up ticket later. -- You discover a bug, doc error, or missing test during the ticket (not pre-planned work). -- Production verification is blocked on something outside the current PR. - -**Cadence (use judgment):** - -| Plan size | Typical updates | -|-----------|-----------------| -| Small (1 PR, <5 files) | Once before opening PR | -| Medium (2–4 atomic commits) | After migration/API contract; before PR | -| Large / multi-repo | Per plan phase + before each PR | - -**Always update progress before opening a PR** for initiatives that use this skill. - -### At handoff - -Leave progress with accurate **Status** lines, open PR URLs, branch names, and “**Next:**” for the successor agent. - ---- - -## Progress file template - -```markdown -# — progress - -**Tracking:** [meshflow-api#NNN](https://github.com/pskillen/meshflow-api/issues/NNN) (and cross-links) -**Plan:** `.cursor/plans/<plan-file>.plan.md` or GitHub issue -**Repos:** meshflow-api, … - ---- - -## Overall status - -**Status:** Not started | In progress | Complete (pending deploy) | Complete - -**Branch:** `api-NNN/<author>/<slug>` (per repo if applicable) - ---- - -## <Phase or slice name> - -**Status:** … -**PR:** … - -**Delivered** - -- … - -**Deploy / verify** - -- … - ---- - -## Next - -- … -``` - -Use checkboxes in **outstanding** only; progress sections use **Status** + bullet lists (see phase-2 examples). - ---- - -## Outstanding file template - -```markdown -# <Title> — outstanding - -Items **skipped**, **incomplete**, or **discovered during execution** — not the plan’s future phases. - -**Tracking:** same as progress file - ---- - -## <area> - -- [ ] … -- [x] … (closed when fixed; keep brief note or link to PR) - -``` - ---- - -## Cursor plan integration - -Every plan that uses progress tracking must include near the top: - -```markdown -## Progress tracking - -Read and update (per [progress-tracking](meshflow-api/.cursor/skills/progress-tracking/SKILL.md)): - -- **Progress:** [docs/features/.../<slug>-progress.md](path) -- **Outstanding:** [docs/features/.../<slug>-outstanding.md](path) - -Update both at logical breakpoints and **before each PR**. -``` - -When a plan depends on another (e.g. enrollment after #362), the dependent plan’s progress file should note **Prerequisite:** link to the other progress file and required merge/deploy state. - ---- - -## GitHub issues - -- Link progress/outstanding paths in the tracking issue body or a comment at kickoff. -- Do not duplicate the full progress log in the issue; the markdown files are canonical for agent handoff. -- Close outstanding items by linking the fixing PR or moving to a new issue if scope grew. - ---- - -## Anti-patterns - -- Copying the plan’s full todo list into outstanding. -- Marking plan phases “done” in progress without PR/commit evidence. -- Creating phase-0/1/2-style files for a single small ticket (one progress pair is enough). -- Letting progress go stale across multiple PRs without a **Next** section. diff --git a/AGENTS.md b/AGENTS.md index 45639732..8be3d203 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,7 +67,7 @@ See **tests/TESTING.md** for detailed instructions (unit tests, integration test ### Pre-production database (opt-in) -Agents must **not** query pre-prod unless the user explicitly enables it. When enabled, follow **[.cursor/skills/preprod-database/SKILL.md](.cursor/skills/preprod-database/SKILL.md)** (`disable-model-invocation`; copy credentials to local `Meshflow/ai-env`, gitignored). +Agents must **not** query pre-prod unless the user explicitly enables it. When enabled, follow the `preprod-database` skill (`MeshFlow/.cursor/skills/preprod-database/SKILL.md`, in the MeshFlow umbrella workspace) (`disable-model-invocation`; copy credentials to local `Meshflow/ai-env`, gitignored). ## Code Style diff --git a/docs/features/meshcore/README.md b/docs/features/meshcore/README.md index d118d49c..38450023 100644 --- a/docs/features/meshcore/README.md +++ b/docs/features/meshcore/README.md @@ -14,7 +14,7 @@ Cross-repo MeshCore work is tracked on GitHub epics [#264](https://github.com/ps | **Feeder enrollment** ([#293](https://github.com/pskillen/meshflow-ui/issues/293)) | [enrollment-progress.md](./enrollment-progress.md) | [enrollment-outstanding.md](./enrollment-outstanding.md) | | **Passive packet path** (Phase 3 slice) | [packet-path-tracing/packet-path-tracing-progress.md](./packet-path-tracing/packet-path-tracing-progress.md) | [packet-path-tracing/packet-path-tracing-outstanding.md](./packet-path-tracing/packet-path-tracing-outstanding.md) | -**Agent convention:** [progress-tracking skill](../../../.cursor/skills/progress-tracking/SKILL.md) — update progress/outstanding at plan breakpoints and before PRs. +**Agent convention:** `progress-tracking` skill (`MeshFlow/.cursor/skills/progress-tracking/SKILL.md`, in the MeshFlow umbrella workspace) — update progress/outstanding at plan breakpoints and before PRs. **Feature guides** (how-to, not phase status):