From 689f2d40ad624c9fa6a87e02a31c2d38f8a855cf Mon Sep 17 00:00:00 2001 From: Andrew Jong Date: Tue, 4 Aug 2026 17:14:46 -0700 Subject: [PATCH 1/3] Add feature-notebook workflow: local design specs + test results per feature Every feature a coding agent implements now gets a numbered entry under notebook/ (gitignored, local-only): a design_spec.md written before coding (problem context from the session, proposed implementation with per-section DESIGN/TODO / WIP / DONE status labels, lettered test plan) and a results/ tree with per-section raw artifacts plus a self-contained results_summary.md (embedded tables + figures) that populates the feature's PR description. - New skill .agents/skills/use-feature-notebook with SKILL.md and design_spec / results_summary templates - AGENTS.md: skill registry row, notebook-first Agent Workflow Example, new "Feature Notebook" section - .gitignore: /notebook/ Co-Authored-By: Claude Fable 5 --- .agents/skills/use-feature-notebook/SKILL.md | 90 +++++++++++++++++++ .../assets/design_spec_template.md | 58 ++++++++++++ .../assets/results_summary_template.md | 32 +++++++ .gitignore | 4 + AGENTS.md | 32 +++++-- 5 files changed, 210 insertions(+), 6 deletions(-) create mode 100644 .agents/skills/use-feature-notebook/SKILL.md create mode 100644 .agents/skills/use-feature-notebook/assets/design_spec_template.md create mode 100644 .agents/skills/use-feature-notebook/assets/results_summary_template.md diff --git a/.agents/skills/use-feature-notebook/SKILL.md b/.agents/skills/use-feature-notebook/SKILL.md new file mode 100644 index 000000000..7a2f2dc8a --- /dev/null +++ b/.agents/skills/use-feature-notebook/SKILL.md @@ -0,0 +1,90 @@ +--- +name: use-feature-notebook +description: Maintain a local, gitignored notebook/ directory that records the design spec and test results for every feature an agent implements. Trigger at the START of any feature-implementation task (create notebook/NNN-feature-slug/design_spec.md before writing code), while implementing (keep the spec's per-section status labels DESIGN/TODO / WIP / DONE current), whenever tests for that feature produce output worth keeping (store under results/
/), and when opening the feature's PR (populate the PR body from results/results_summary.md). +license: Apache-2.0 +metadata: + author: AirLab CMU + repository: AirStack +--- + +# Skill: Use the Feature Notebook + +## Purpose + +Every feature implemented by a coding agent gets a **notebook entry**: a numbered folder under `notebook/` at the repo root that holds the design spec written *before* implementation and the test results produced *during* validation. The notebook is the agent's lab journal — it captures the session context that would otherwise be lost when the conversation ends, and it is the source material for the feature's PR description. + +`notebook/` is **gitignored and local-only**. It never lands in a commit. Each developer's machine has its own copy. What *does* leave the machine is the distilled content: the PR body is populated from `results/results_summary.md`, and figures/tables from `results/` are attached to the PR. + +## Directory Layout + +``` +notebook/ +├── 001-add-new-planner/ +│ ├── design_spec.md # Written BEFORE implementation +│ └── results/ +│ ├── results_summary.md # Written AFTER tests; feeds the PR +│ ├── a-planner-core/ # Raw artifacts for test section (a) +│ │ ├── run1_metrics.json +│ │ └── trajectory_plot.png +│ └── b-planner-hyperparameters/ # Raw artifacts for test section (b) +│ └── sweep_table.csv +├── 002-fix-lidar-filter/ +│ └── ... +``` + +Naming rules: + +- **Feature folder:** `NNN-short-kebab-slug`, where `NNN` is zero-padded three digits. Pick the next number by listing `notebook/` and incrementing the highest existing prefix (start at `001` if empty or missing — create `notebook/` yourself, it is not committed). +- **Results subfolders:** one per lettered test section in `design_spec.md`, named `-` (e.g. section "(a) Planner core" → `results/a-planner-core/`). The letters MUST match the test-plan section letters in the spec so a reader can navigate spec ↔ results directly. + +## Workflow + +### 1. On starting a feature — write `design_spec.md` + +Before writing any implementation code, create `notebook/NNN-feature-slug/design_spec.md` from [assets/design_spec_template.md](assets/design_spec_template.md). It must capture: + +- **Problem context** — what the developer is trying to solve, in the developer's own framing from the session: motivation, constraints, prior attempts, and any decisions already made in the conversation. This is the section that preserves context which exists nowhere else. +- **Proposed implementation** — the design: affected packages, new/changed nodes and topics, algorithms, data flow. Diagrams (mermaid) welcome. Split into subsections if the implementation has multiple parts. +- **Test plan** — lettered sections `(a)`, `(b)`, `(c)`… each describing one validation axis: what is run (unit test, system test mark, sim scenario), what is measured, and what outcome counts as pass. These letters define the `results/` subfolder names. + +If the design changes materially mid-implementation, update the spec — it should describe what was actually built, with a short note on what changed and why. + +### 2. While implementing — keep the spec's status labels current + +`design_spec.md` carries an implementation status at two levels, using the values **`DESIGN/TODO`**, **`WIP`**, or **`DONE`**: + +- **Overall status** in the header block — the least-advanced status of any implementation section (all sections `DONE` → overall `DONE`; anything in progress → `WIP`; nothing started → `DESIGN/TODO`). +- **Per-section status** on each Proposed Implementation subsection heading (e.g. `### 2.1 Cost-map integration — \`WIP\``) — so when the implementation has multiple parts, a reader can see exactly which parts are designed, in progress, or finished. + +Update the labels **as you work**, not retroactively: mark a section `WIP` when you start writing its code and `DONE` when it is implemented and building. A spec whose statuses lag reality misleads the next agent that picks up the feature. + +### 3. During validation — store raw results + +Every test run that validates the feature drops its artifacts into the matching section folder, e.g. `notebook/001-add-new-planner/results/a-planner-core/`: + +- Metrics files (`metrics.json`, CSVs), copied from `tests/results//` when using the system test harness +- Plots and screenshots (cross-track error curves, Foxglove/RViz captures, sim screenshots) +- Relevant log excerpts — excerpts, not full container logs + +Keep raw artifacts as-produced; interpretation belongs in the summary. + +### 4. After validation — write `results/results_summary.md` + +Create `results/results_summary.md` from [assets/results_summary_template.md](assets/results_summary_template.md). One section per test-plan letter, mirroring the spec. The summary must be **self-contained**: embed the quantitative tables and qualitative figures directly in the document (markdown tables; images via relative paths like `![xte](a-planner-core/trajectory_plot.png)`) so a developer can understand the results all at once without opening the raw artifact folders. End with an overall verdict: which spec sections passed, which didn't, known limitations. + +### 5. On opening the PR — populate it from the notebook + +The PR body for the feature is built from the notebook, since reviewers cannot see `notebook/` itself: + +- **Motivation / context** ← `design_spec.md` problem context +- **What changed** ← proposed implementation (as-built) +- **Validation** ← `results_summary.md`: paste the summary tables, upload the key figures as PR attachments, and state the per-section verdicts + +## Pitfalls + +- ❌ Writing the spec after the code — the spec exists to record intent and session context before they're lost. +- ❌ Stale status labels — a spec still marked `DESIGN/TODO` (or a section marked `WIP`) after the work shipped misleads the next reader; update statuses as you go. +- ❌ Committing `notebook/` or referencing `notebook/...` paths from committed code, docs, or tests — it doesn't exist on other machines or in CI. +- ❌ Results subfolder letters that don't match the spec's test-plan letters. +- ❌ A `results_summary.md` that just links to raw files — embed the tables and figures. +- ❌ Confusing this with [capture-discovered-knowledge](../capture-discovered-knowledge): the notebook records *per-feature* design and evidence locally; durable repo-wide knowledge still goes to AGENTS.md/skills, and module documentation still follows [update-documentation](../update-documentation). diff --git a/.agents/skills/use-feature-notebook/assets/design_spec_template.md b/.agents/skills/use-feature-notebook/assets/design_spec_template.md new file mode 100644 index 000000000..ecb184ba2 --- /dev/null +++ b/.agents/skills/use-feature-notebook/assets/design_spec_template.md @@ -0,0 +1,58 @@ +# Design Spec: + +> Notebook entry: `notebook/NNN-feature-slug/` · Date started: YYYY-MM-DD · Branch: `` +> +> **Status: `DESIGN/TODO`** + +## 1. Problem Context + + + +## 2. Proposed Implementation + + + +### 2.1 — `DESIGN/TODO` + + + +### 2.2 — `DESIGN/TODO` + + + +### Affected packages + +| Package | Change | +|---------|--------| +| `path/to/package` | ... | + +### Interfaces + +| Topic / Service / Param | Type | Direction | Purpose | +|-------------------------|------|-----------|---------| +| | | | | + +## 3. Test Plan + + + +### (a)
+ +- **What is run:** +- **What is measured:** +- **Pass criteria:** + +### (b)
+ +- **What is run:** +- **What is measured:** +- **Pass criteria:** diff --git a/.agents/skills/use-feature-notebook/assets/results_summary_template.md b/.agents/skills/use-feature-notebook/assets/results_summary_template.md new file mode 100644 index 000000000..5f3b0977f --- /dev/null +++ b/.agents/skills/use-feature-notebook/assets/results_summary_template.md @@ -0,0 +1,32 @@ +# Results Summary: + +> Spec: [`../design_spec.md`](../design_spec.md) · Date: YYYY-MM-DD · Commit tested: `` + + + +## (a)
+ +**Setup:** + +| Metric | Value | Pass criterion | Pass? | +|--------|-------|----------------|-------| +| | | | | + +![description](a-section-slug/figure.png) + +**Interpretation:** + +## (b)
+ +... + +## Overall Verdict + +| Spec section | Verdict | +|--------------|---------| +| (a) ... | ✅ / ❌ | +| (b) ... | ✅ / ❌ | + +**Known limitations:** diff --git a/.gitignore b/.gitignore index 4868b5c74..d9dd6a07b 100644 --- a/.gitignore +++ b/.gitignore @@ -94,6 +94,10 @@ simulation/ms-airsim/assets/scenes/* # Test results tests/results/ +# Per-feature agent notebook (design specs + test results) — local-only, feeds PR descriptions. +# See .agents/skills/use-feature-notebook +/notebook/ + # Local-only — embedded sibling repo, not part of this branch common/rayfronts/ diff --git a/AGENTS.md b/AGENTS.md index 1579006ec..88d524483 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,17 +100,37 @@ For detailed step-by-step instructions, refer to the **`.agents/skills/`** direc | [configure-multi-robot](.agents/skills/configure-multi-robot) | Setting up multiple robots, ROBOT_NAME namespacing, and ROS_DOMAIN_ID isolation | | [bump-version-and-release](.agents/skills/bump-version-and-release) | Bumping `.env` VERSION and CHANGELOG before merge to clear the version-check gate | | [capture-discovered-knowledge](.agents/skills/capture-discovered-knowledge) | After long context-discovery / surprising findings, persist to AGENTS.md or a new skill so the next agent doesn't redo the work | +| [use-feature-notebook](.agents/skills/use-feature-notebook) | At the start of EVERY feature implementation: create `notebook/NNN-feature-slug/design_spec.md`, store test artifacts under `results/`, write `results/results_summary.md`, and populate the PR from it | **Agent Workflow Example:** -1. Study reference implementation for module type -2. Follow `add_ros2_package.md` to create package structure -3. Implement algorithm with proper topic interfaces -4. Follow `integrate_module_into_layer.md` to add to bringup -5. Follow `update_documentation.md` to document -6. Follow `debug_module.md` and `test_in_simulation.md` to verify +1. **Create a notebook entry** — follow `use-feature-notebook` to write `notebook/NNN-feature-slug/design_spec.md` (problem context, proposed implementation, lettered test plan) before writing code +2. Study reference implementation for module type +3. Follow `add_ros2_package.md` to create package structure +4. Implement algorithm with proper topic interfaces +5. Follow `integrate_module_into_layer.md` to add to bringup +6. Follow `update_documentation.md` to document +7. Follow `debug_module.md` and `test_in_simulation.md` to verify, saving artifacts under `notebook/NNN-feature-slug/results/-
/` +8. Write `results/results_summary.md` (embedded tables + figures) and populate the PR body from it Also see: [AI Agent Quick Guide](docs/development/ai_agent_guide.md) +## Feature Notebook (`notebook/`) + +Every feature an agent implements gets a numbered entry under `notebook/` at the repo root — a local lab journal that survives the agent session: + +``` +notebook/001-add-new-planner/ +├── design_spec.md # BEFORE coding: problem context from the session, proposed implementation, lettered test plan +└── results/ + ├── results_summary.md # AFTER testing: self-contained doc with embedded tables + figures, per-section verdicts + ├── a-planner-core/ # Raw artifacts per test-plan section (letters match design_spec.md) + └── b-planner-hyperparameters/ +``` + +`notebook/` is **gitignored — local-only on each developer's machine**. Never commit it or reference its paths from committed code. Its content leaves the machine one way: the feature's PR description is populated from `design_spec.md` (motivation, what changed) and `results_summary.md` (validation tables, figures uploaded as PR attachments). + +**Full workflow and templates:** [.agents/skills/use-feature-notebook](.agents/skills/use-feature-notebook) + ## Reference Implementations Study these well-structured modules as examples for different types: From d1364bef53ef5341ba0c0d5c8673166485f1af97 Mon Sep 17 00:00:00 2001 From: Andrew Jong Date: Tue, 4 Aug 2026 17:14:53 -0700 Subject: [PATCH 2/3] Bump version to 0.19.0-alpha.10 Co-Authored-By: Claude Fable 5 --- .env | 2 +- CHANGELOG.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.env b/.env index c9527e1f8..020228fa2 100644 --- a/.env +++ b/.env @@ -12,7 +12,7 @@ PROJECT_NAME="airstack" # If you've run ./airstack.sh setup, then this will auto-generate from the git commit hash every time a change is made # to a Dockerfile or docker-compose.yaml file. Otherwise this can also be set explicitly to make a release version. # auto-generated from git commit hash -VERSION="0.19.0-alpha.9" +VERSION="0.19.0-alpha.10" # Choose "dev" or "prebuilt". "dev" is for mounted code that must be built live. "prebuilt" is for built ros_ws baked into the image DOCKER_IMAGE_BUILD_MODE="dev" # Where to push and pull images from. Can replace with your docker hub username if using docker hub. diff --git a/CHANGELOG.md b/CHANGELOG.md index 43940f0b7..5a6673928 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Feature notebook workflow (`use-feature-notebook` skill): every agent-implemented feature gets a local, gitignored `notebook/NNN-feature-slug/` entry with a status-tracked `design_spec.md` (written before coding) and `results/` artifacts + self-contained `results_summary.md` that populate the feature's PR description - Battery and telemetry display in GCS RQT control panel (voltage and percentage per robot when MAVROS battery topic is bridged) - `TARGET_ARCH` build arg (default `x86_64`) in `Dockerfile.robot` to arch-parametrize `LD_LIBRARY_PATH`; `docker-compose.yaml` passes `TARGET_ARCH: aarch64` to the `voxl` and `l4t` real-robot image builds - `ros-${ROS_DISTRO}-mavros-extras` in the robot image (provides the vision_pose plugin used for external-pose deployments) From 8da9eaf5a07edb0cdefba686758e15bbcebf672a Mon Sep 17 00:00:00 2001 From: Andrew Jong Date: Tue, 4 Aug 2026 17:18:26 -0700 Subject: [PATCH 3/3] Document the feature notebook workflow under Development docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/development/intermediate/feature_notebook.md (directory layout, 5-step workflow, status labels, local-only rule, notebook → PR flow), wires it into the mkdocs nav under Development > Intermediate Tutorials > Contributing, and lists it in the Development index. Co-Authored-By: Claude Fable 5 --- docs/development/index.md | 1 + .../intermediate/feature_notebook.md | 67 +++++++++++++++++++ mkdocs.yml | 3 +- 3 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 docs/development/intermediate/feature_notebook.md diff --git a/docs/development/index.md b/docs/development/index.md index a1ccd4663..9ddd13678 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -34,6 +34,7 @@ Welcome to AirStack development! This guide will help you extend and customize t - **[Docker Build Profiles](intermediate/docker-build-profiles.md)** - Robot image build args and platform profiles (`robot-desktop`, `robot-l4t`, etc.) - **[Contributing](intermediate/contributing.md)** - Contribute to AirStack - **[Documentation Guide](intermediate/documentation.md)** - Write great documentation +- **[Feature Notebook](intermediate/feature_notebook.md)** - Record design specs and test results per feature; populate PRs from them ### 🚀 Advanced Tutorials diff --git a/docs/development/intermediate/feature_notebook.md b/docs/development/intermediate/feature_notebook.md new file mode 100644 index 000000000..10dc776a9 --- /dev/null +++ b/docs/development/intermediate/feature_notebook.md @@ -0,0 +1,67 @@ +# Feature Notebook + +Every feature implemented with a coding agent gets a **notebook entry**: a numbered folder under `notebook/` at the repository root that records the design spec *before* implementation and the test results *after*. The notebook is a lab journal — it preserves the session context (problem framing, design decisions, validation evidence) that would otherwise be lost when the agent conversation ends, and it is the source material for the feature's pull request description. + +!!! warning "Local-only" + `notebook/` is **gitignored**. It never lands in a commit, and committed code, docs, and tests must never reference `notebook/...` paths — the directory doesn't exist on other machines or in CI. Its content leaves your machine one way: distilled into the feature's PR description. + +## Directory Layout + +```text +notebook/ +├── 001-add-new-planner/ +│ ├── design_spec.md # Written BEFORE implementation +│ └── results/ +│ ├── results_summary.md # Written AFTER tests; feeds the PR +│ ├── a-planner-core/ # Raw artifacts for test section (a) +│ │ ├── run1_metrics.json +│ │ └── trajectory_plot.png +│ └── b-planner-hyperparameters/ +│ └── sweep_table.csv +├── 002-fix-lidar-filter/ +│ └── ... +``` + +- **Feature folders** are named `NNN-short-kebab-slug` with a zero-padded three-digit prefix. Pick the next number by incrementing the highest existing prefix (start at `001`). +- **Results subfolders** are named `-`, one per lettered test-plan section in `design_spec.md` — section "(a) Planner core" maps to `results/a-planner-core/` — so a reader can navigate spec ↔ results directly. + +## Workflow + +### 1. Before coding — write the design spec + +Create `notebook/NNN-feature-slug/design_spec.md` with three parts: + +- **Problem context** — what you're trying to solve, in your own framing from the session: motivation, constraints, prior attempts, decisions already made. This is the section that preserves context which exists nowhere else. +- **Proposed implementation** — affected packages, new/changed nodes and topics, algorithms, data flow. Split into subsections if the implementation has multiple parts. +- **Test plan** — lettered sections `(a)`, `(b)`, `(c)`…, each describing what is run, what is measured, and what counts as pass. + +### 2. While implementing — keep status labels current + +The spec carries an implementation status at two levels, using **`DESIGN/TODO`**, **`WIP`**, or **`DONE`**: + +- An **overall status** in the header — the least-advanced status of any implementation section. +- A **per-section status** on each implementation subsection heading (e.g. `### 2.1 Cost-map integration — WIP`), so a reader sees exactly which parts are designed, in progress, or finished. + +Update labels as you work, not retroactively — a spec whose statuses lag reality misleads the next person (or agent) who picks up the feature. + +### 3. During validation — store raw results + +Each test run drops its artifacts into the matching lettered section folder: metrics files (e.g. `metrics.json` copied from `tests/results//`), plots, sim screenshots, and relevant log *excerpts*. Keep raw artifacts as-produced; interpretation belongs in the summary. + +### 4. After validation — write the results summary + +Write `results/results_summary.md` with one section per test-plan letter. It must be **self-contained**: embed the quantitative tables and qualitative figures directly in the document (markdown tables; images via relative paths) so a developer can understand all the results at once without opening the raw artifact folders. End with an overall verdict — which spec sections passed, which didn't, and known limitations. + +### 5. Opening the PR — populate it from the notebook + +Reviewers can't see `notebook/`, so the PR body carries the distilled content: + +| PR section | Source | +|------------|--------| +| Motivation / context | `design_spec.md` problem context | +| What changed | Proposed implementation (as-built) | +| Validation | `results_summary.md` — paste the tables, upload key figures as PR attachments, state per-section verdicts | + +## Templates and Agent Skill + +Fill-in templates for both documents, and the full agent-facing workflow (including pitfalls), live in the [`use-feature-notebook` skill](https://github.com/castacks/AirStack/tree/develop/.agents/skills/use-feature-notebook) under `.agents/skills/`. Coding agents are instructed via `AGENTS.md` to follow this workflow at the start of every feature implementation. diff --git a/mkdocs.yml b/mkdocs.yml index e75d85bc7..a36d4c75f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,9 +73,10 @@ nav: - CI/CD Orchestrator: tests/ci-cd-orchestrator.md - Frame Conventions: docs/development/intermediate/frame_conventions.md - Docker Build Profiles: docs/development/intermediate/docker-build-profiles.md - - Contributing: + - Contributing: - docs/development/intermediate/contributing.md - docs/development/intermediate/documentation.md + - Feature Notebook: docs/development/intermediate/feature_notebook.md - Advanced Tutorials: - AI Agent Guide: docs/development/advanced/ai_agent_guide.md - AirStack CLI Tool: