AI-Assisted Development Guide

Related documents

• Development Process Guide
• Coding Style Guide
• How to Make a New Aircraft App
• Extracting POH Data with an AI Agent
• Scripts Reference
• Directory Layout
• Ptable Reference
• acType Reference
• unitTest Reference

Table of contents

• How to use this guide
• The project in brief
• Working rules
  • Version control
  • Changes usually apply to every aircraft app
  • Ask, don't guess
• Aircraft data rules
  • Numbers must match the POH literally
  • Base methods and model methods
  • Model inheritance
  • Ptable details
  • Aircraft-specific behavior must be data-driven
  • Options
• Code rules
  • State variables and templates
  • Native platform constraints
• Testing and verification
  • Commands
  • Writing tests
  • Checking against V4
  • Checking the UI
• Documentation
• Known behaviors that are not bugs
• Before you hand back a change
• Prompts for common tasks
  • Start a session
  • Fix a bug
  • Digitize a POH's graphs
  • Extract POH tables for audit
  • Add or port an aircraft model
  • Add an aircraft option
  • Audit data against the POH
  • Review a change
  • Write or update documentation

How to use this guide

This guide collects the rules, conventions and hard-won lessons for changing the V5 code on the develop branch with an AI coding agent. It is written for both people and agents: each rule says what to do and why, so an agent can apply it and a person can judge when it doesn't fit.

To use it, point your agent at this file at the start of a session. For example:

Before making any change, read version5/doc/dev/aiGuide.md and follow it. Also read the documents it links to when a task touches their area.

Agents that read a project instruction file find this guide on their own: CLAUDE.md in the repository root imports it for Claude Code, and AGENTS.md points other agents to it. When version5/ moves to the repository root, drop the version5/ prefix from these paths and from both files.

Developers: you are expected to have good coding skills and to know this codebase and its rules. AI agents are your development partners. They know general best practices widely, but their working memory doesn't hold the whole codebase, so they sometimes patch a symptom where a higher-level change is needed. Review all AI-generated code before you check it in.

Agents: act as a trusted development partner, not just an order-taker. Treat the rules in this document as project policy: where one conflicts with a general habit of yours (for example committing after every change, or adding explanatory comments), the rule here wins. If a request conflicts with this guide or with general good practice, or a fix looks like a local patch for a problem that belongs at a higher level, say so before acting: name the rule or practice, explain the risk and suggest an alternative. Raise real problems, not matters of taste. The developer has the final say. Once they decide, do it their way without reopening the question, and never quietly do something different. If they overrule a rule in this guide, mention it in your report so a reviewer can see it.

The project in brief

• POH Performance is a family of aircraft performance apps. Each aircraft app (Baron, Bonanza, C172, C182, C310, Kodiak, PA28, TBM) computes takeoff, climb, cruise, landing and weight-and-balance results from the aircraft's Pilot's Operating Handbook (POH) data. Radar is a separate utility app. Testapp and Example1 are development fixtures.
• This is a safety-critical pilot tool. A wrong number can mislead a pilot. Correctness and verifiability come before cleverness, brevity or speed.
• V5 lives in version5/ and is the product. version4/ is the legacy code base; change it only when asked. Once every app has shipped on V5, version4/ will be deleted and the contents of version5/ will move to the repository root. Paths in this guide are relative to the V5 project root, currently version5/.
• Every app is a Progressive Web App built from source/app/<App>/buildStamp/ plus the shared source/app/common/. Native iOS and Android apps are built from the same web image with Cordova. See Directory Layout.
• The framework is MVCS (Model-View-Controller-State). Pages declare state variables (SVs), computes and tml templates. Start with the MVCS Overview.

Working rules

Version control

• Work on the develop branch. Don't create a feature branch or a separate worktree unless the developer asks for one.
• Don't commit unless the developer explicitly asks. Report what changed and leave it uncommitted.
• When asked to commit:
  • Stage only the files the developer named. Run git diff on each first: the developer may be editing the same files at the same time, so commit only your own hunks, or ask.
  • Use the title format V5 <App>: <summary>, for example V5 TBM: Fix enroute data errors found in PIM audit. Use V5 All: for a change to every app, a comma list for a few (V5 Baron,C310:), V5 Doc: for documentation and Common: for common code. Keep the message to the title and a few short bullets.
  • When asked for one commit across several apps, make exactly one.
• Never push, rebase shared branches, or rewrite history unless asked.

Changes usually apply to every aircraft app

The aircraft apps share near-duplicate files: page/aircraft.js, page/weightBalance.js, page/enroute.js, aircraftData/typeData.js and their siblings exist in each app with small differences. A fix in one app's file almost always belongs in the others.

• Before editing a file outside source/app/common/, grep the same code anchor across source/app/*/buildStamp/ to learn the real scope.
• Patch every app that matches, and verify each one rather than assuming uniformity: the same logic often has a slightly different shape in each app (a different message, an extra seat variant, a method in baseMethods instead of inline).
• Report which apps you changed and which you deliberately left alone, with the reason.

Ask, don't guess

• If a POH value, a design choice or the scope of a change is unclear, ask the developer. Don't fill gaps in aircraft data with plausible numbers.
• When you find a problem outside the task, report it rather than fixing it silently.

Aircraft data rules

Aircraft data lives in source/app/<App>/buildStamp/aircraftData/. The main reference is How to Make a New Aircraft App.

Numbers must match the POH literally

A reviewer must be able to open the POH page and see the same digits in the code.

• Keep raw POH values in tables. When the POH's units differ from the app's default units, which typeData.js sets with Ptable.defaultUnits(), declare them on the Ptable axis or output (units:'mph', units:'dF', units:'pph'). The Ptable converts at query time. Don't pre-convert values to knots or Celsius, and don't add // 60 mph comments next to converted literals.

  inputs: ['flaps', {key:'ias', limit:'offset', units:'mph'}],
  output: {key:'cas', rndMult:1, units:'mph'},
  

• When a value really is derived, write the derivation inline from the POH number so it can be checked:

  {p:1600, v:mphToKt(55 - 6)},          // 55 mph CAS, POH p. 3-9, less 6 mph = IAS
  

  not {p:1600, v:42.6}.
• When a value must be interpolated or extrapolated by hand, use interpolate(x, x1, y1, x2, y2) with the POH values as its arguments:

  {p:1870, v:interpolate(50, 0, 1870, 41, 7000)},    // extrapolated
  

• Scalar adjustments that are not table axes (for example tasNoFairingAdj: mphToKt(-2)) may use conversion functions.
• Don't reuse another model's tables unless the two POHs are literally identical for that data. Different revisions, units or chart shapes mean the model gets its own tables.
• The POH is the primary source. Where it doesn't give a value, such as the serial numbers, the CG envelope as numbers, or the tank arms and usable fuel, take it from the type certificate data sheet (TCDS) and cite the TCDS, its revision and section. Where the POH does give a value, the POH wins: don't override or extend it from the TCDS.
• Cite the source (figure, table or page) in a comment on each table.
• POH worked examples are sometimes wrong; the charts and tables are authoritative.
• Never sample a POH graph straight into a model: an agent's samples aren't accurate enough. Build a Digitizer project with the graphs calibrated and sampled for the developer to check, as described in Extracting POH Data with an AI Agent. Put transcribed tables in the project too, so they can be compared with the model.

Base methods and model methods

Each aircraft type's typeData.js holds a set of base methods for each phase of flight (tko.roll, climb.rate, cruise.tas and so on). They fit a large set of the type's models, usually the newer ones, and every model gets them without declaring them. See Create the type data and Type-wide data.

• Put a model-specific difference in a method of the same name in the model's data file, which overrides the base method for that model. The override can reuse shared helpers from typeData.js.
• Don't add cases for particular models to a base method, whether by model ID, serial number or a data flag only one model sets. A base method that branches on models soon becomes spaghetti that no one can verify against any single POH.
• Change a base method only for behavior that is right for every model that uses it.

Model inheritance

• Use spread (...parentData, fuel: otherData.fuel) to inherit a few individual items or tables.
• Use modelDataMergeUnder(child, parent) (child wins) or modelDataMergeOver from the app's typeData.js to inherit whole sub-objects such as wb, tko, climb, cruise or ldg.
• Pass a model's data object to acType.createModel by reference. Never pass objectCopy(data): other files (for example circuit-breaker panels) attach to the data object after the model is created.
• A model that has its own climb or cruise data must declare maxAltitude explicitly rather than inherit it.
• maxAltitude must not exceed the extent of either the climb or the cruise tables. If it does, the enroute climb to cruise altitude has no data and every cruise output goes blank, with no error.

Ptable details

• By default, an out-of-range input makes interpolate() return an error value (test it with Ptable.isPtableError(); it displays as a struck-through "POH"). It throws only when asked to, with interpolateT() or the throwError option. See Range errors. An axis limit changes what happens out of range:
  • clamp pins both ends; clampLo and clampHi pin one end and return an error on the other.
  • offset extrapolates by parallel shift on both ends. It is only valid when the output key matches the first input key (adjustment tables, IAS-to-CAS), because the shift is applied in the input's units. For a weight-to-speed table use clamp.
• Every weight and pressureAltitude input gets limit:'clampLo' (or clamp), so a lighter weight or lower altitude than the POH charts uses its lowest line instead of failing.
• rndMult rounds after conversion to the app's internal unit. A units:'pph' fuel-flow table with rndMult:1 rounds to whole gallons per hour; use rndMult:0.1. Never put a coarse rndMult on a multiplicative factor table.
• A table of pph values with no units on its output is read in the app's default fuel-flow units (gph). Check the POH's units against the defaults in typeData.js for every table.

Aircraft-specific behavior must be data-driven

• Never key behavior or Help text on a model name (sv.ac_model.value === 'C310Q'). The next model with the same characteristics will be missed. Derive it from the model's data (table limits, input keys, row counts), or add a small declared data key, and write "the POH" rather than a model name in user-visible text.
• IOAT/OAT conversions must check acData.hasStaticAirTemperature (and acData.satOffset on the TBM). A model merged under a model with static air temperature inherits the flag and must set it to false explicitly if its panel shows total air temperature.

Options

• An option has optionOn (selectable on matching serials) or installedOn (fitted by the model), or both. Their values are applicability strings, described in Applicability string. The model part is a RegExp, so it can match more models than intended when one model ID contains another; anchor it with ^ and $ when that happens. A malformed string matches nothing, silently, so test that the option appears where it should.
• The option card hides options the user has no choice about (installedOn, or pulled in by another option's includes). A greyed-out row is only for a real choice that another selection ruled out (optClass, incompatibleWith, a removed enabledBy). options.permanent is the set of hidden options; if you add a mechanism that installs an option behind the user's back, add it to permanent.

Code rules

Follow the Coding Style Guide. The points agents most often miss:

• Tabs, set to 2 columns. Lines of 80 characters or less.
• return (value);, a space before the parameters in a function definition and none in a call, case aligned with switch, + without spaces for string concatenation.
• Trailing comments start at column 41, counting tabs as 2 columns; use one tab when the code already reaches that column. Align only the lines you add or change.
• Keep comments concise: state the rule and any non-obvious reason in a sentence or two. Don't narrate the change, give worked examples or corpus numbers.
• References to V4 belong only in V4-to-V5 upgrade code (upgradeSavedState(), upgradeAircraftToV5(), idTranslations and the like). Elsewhere, describe the V5 rule without its history.
• Match the surrounding code's naming, idiom and comment density.
• common/script/localDevice.js only detects the platform. Code that acts on it, such as adding a class to <html>, goes in each app's app.js.

State variables and templates

• Every {{id}}, hasChanged= and hasValue= in a tml template must name a declared SV. make lint runs tmlLint.js to check this. If it reports an id as unexpandable, teach tmlLint.js the new declaration form; never add a wildcard.
• A bad reference inside a gated <When> or option-only card only fails when that condition first renders, which is why the lint check exists.
• In tml text, write & for a literal ampersand. A bare & followed by word characters and a later ; in the same string is parsed as a character entity.
• tml trims leading and trailing whitespace from text, so a multi-line template string (a dataSource, say) needs no trimming and its whitespace can't cause a layout problem.
• In procedure TML, an option-gated group must carry its option="..." (or option="!...") attribute. A <ClConditionalGroup> or <ClBody> without one always shows.
• SV.infoBasedOn() deep-copies the base info. To change a default for a whole app, mutate the exported base info at app.js module scope before startup creates the SVs.
• On a unit input, a top-level dflt works, but top-level min and max are ignored; set them per unit.
• assert() (in util.js) logs and alerts but does not throw, so code after a failed assert keeps running. Don't rely on it to stop bad state.
• Only a user-triggered sync should have user-visible side effects such as deselecting a trip. Use InputSv.userChange (which sets ctl.userChangedSv) for user actions, not valSync.

Native platform constraints

These matter even for web-only changes because the same code ships natively.

• Never change the WebView scheme or hostname in a config.xml. Saved user data lives in localStorage, which is scoped to the origin, so a change silently loses every user's data on update. V5 iOS is app://localhost, Android is https://localhost. V5 cannot run on file:// at all (ES modules don't load).
• On native Android, cordova-android already keeps content clear of the system bars; CSS must not add safe-area padding there (html.nativeAndroid handles it).
• Never resolve prefers-reduced-motion to no animation for a progress or activity indicator: a frozen spinner reads as a hang. Use a cross-fade instead.
• Client features must meet the criteria in Technology use.

Testing and verification

Verify every change before reporting it as done, and say exactly what you checked and what you could not.

Commands

Run these from the V5 project root:

• The web build is incremental on source times. A file edited by hand under build/web survives a rebuild; remove build/web/<App> to force one.
• Expected noise from selfTestRun.js on a failing run: failed startSession and setSavedInput requests and a PAGEERROR: Response. A passing run prints one line.
• The developer may have make serve running. It rebuilds whenever anything under source/ changes, including generated files such as airport databases. Don't write scratch output under source/, and check for a running make serve before running builds that could race it.

Writing tests

Tests are written with unitTest. A complete aircraft model has all three kinds:

1. System tests, in the page files: set SVs the way a user would (setAc(), selectAcOption(), sv.x.valSync()) and check output SVs. Most expensive; covers the most.
2. Method tests, in the model files: call aircraft methods directly (acData.tko.roll(conditions)).
3. Table tests: call Ptable.interpolate() directly. Cheapest.

Rules for tests:

• Test an option by looking up a value where the option's data differs from the base model, through acData. Never assert only options.installed.includes(...): that passes even when the option's data failed to merge.
• Switch models and options in tests with the page/aircraft.js helpers setAc(), selectAcOption() and unselectAcOption(), not acType.setAcData(), which skips the merge.
• Scenario groups start with unitTest.resetScenario() so they are independent of group order.
• Close table-coverage gaps with UI-level scenarios, not direct method calls, which would hide the bugs the gap points to.
• In scenario scripts, set the enroute altitude before ISA and wind: changing the altitude resets them.
• Take expected values from the POH and cite where they came from. Never copy the app's current output into a test as the expected value.

Checking against V4

Until version4/ is removed, tools/upgradeToV5/*Diff.js (for example node tools/upgradeToV5/baronDiff.js --all) runs the same scenarios through the V4 and V5 engines and passes when every difference is on its KNOWN list of deliberate changes. When a harness and V5 disagree, check the harness's V4 expression against the V4 page code before blaming V5. A V4 installedOn option that became optionOn in V5 is drift that the self-tests can't see.

Checking the UI

• Verify UI changes in the web build (make serve, then http://localhost:8000), not in device simulators, unless the change is native-specific.
• It's fine to accept the Terms of Use popup in a local development build.
• Browser tabs run by an agent are often hidden, which throttles timers and freezes CSS animations. A long self-test run can look hung when it isn't, and animation and paint timing can't be measured there.
• A service worker serves cached files, so network throttling proves nothing about load time. Use the ?splashAfter=<ms>, ?splashHold=<ms> and ?splashOff=1 hooks in index.html instead.

Documentation

• Update the documentation in doc/ in the same change as the behavior it describes. Follow the Markdown style.
• make doc regenerates each file's table of contents and the MVCS index in place. Commit those generated changes with the edit that caused them, and run make checkMdLinks.

Known behaviors that are not bugs

Don't report these as findings:

• Bonanza and Baron POH stall speeds can fall as weight rises, because the POH assumes the CG moves aft. Exempt them from monotonicity checks.
• Changing the cruise altitude resets a manually entered wind and, with no airports set, the ISA deviation. This is a known design issue.
• Cloud Sync identifies a user by an unverified email and a "security word" stored in plain text. This is a deliberate low-friction design for low-sensitivity data. Trouble-report ids are guessable by design. The one point worth raising is wording that invites users to reuse a real password.

Before you hand back a change

• The change is applied to every app it belongs in, and you've listed the apps you skipped and why.
• Aircraft data matches the POH digit for digit, with units declared and sources cited.
• make lint is clean and make <App>.test passes for each app you touched.
• New behavior has tests whose expected values come from the POH.
• Documentation is updated.
• Nothing is committed unless the developer asked.
• Your report says what you verified, what you didn't, and anything you noticed but left alone.

Prompts for common tasks

Each prompt assumes the agent has already read this guide. Replace the angle-bracket parts.

Some POH tasks are also skills, in .claude/skills/ at the repository root:

• digitize-poh builds a Digitizer project from a POH: /digitize-poh <POH pdf> <App> <reference model>.
• ppdig-to-model makes a model data file from a checked project: /ppdig-to-model <ppdig> <App> <reference model>.
• compare-pohs reports which graphs and tables two POHs of one type share and which differ: /compare-pohs <POH A pdf> <POH B pdf> <App> <reference model>.
• model-to-ppdig re-verifies a model's data: it builds a Digitizer project from the POH whose samples and rows are the model's own values, and reports where they miss the page: /model-to-ppdig <POH pdf> <App> <model>.

Run them in Claude Code as shown. Tell any other agent to read and follow the skill's SKILL.md.

Start a session

Read version5/doc/dev/aiGuide.md and the documents it links to for this task. Summarize the rules that apply before you start, then wait for my go-ahead.

Fix a bug

In the V5 <App> app, <describe symptom and how to reproduce>. Find the root cause before changing anything and explain it. Then check whether the same code exists in the other aircraft apps and fix it everywhere it applies. Add a self-test that fails without the fix, run make lint and make test, and report which apps you changed. Don't commit.

Digitize a POH's graphs

First have the agent list what the POH has and map it to a reference model's data paths, then correct the list it makes and give it as <list>. See Starting an agent for that prompt. The digitize-poh skill runs both steps and stops for your corrections in between.

Build the Digitizer project digitized/<App>/<document>.ppdig from the POH at <path>, following doc/dev/aiDigitizing.md. Calibrate and sample the graphs in this list, with the data paths it gives, and leave out the items it marks to leave out: <list>. Give each graph its POH title and source, and look at a ppdig render of each one. Run ppdig check, and report your confidence in each graph and anything you left out. Don't change aircraftData.

Extract POH tables for audit

Transcribe the tables in this list, with the data paths it gives, from the POH at <path> into the Digitizer project digitized/<App>/<document>.ppdig, following doc/dev/aiDigitizing.md: <list>. Run ppdig check, then compare the project with the <model> model using make <App>.ppdigCompare. List each difference with the POH page, the POH value and the code value. Don't change anything else.

Add or port an aircraft model

Add the <model> to the V5 <App> app from the POH at <path>, following doc/dev/newAircraft.md. Take graph data only from a Digitizer project the developer has checked; if there isn't one, stop and digitize the graphs first. Keep every number as printed in the POH with units: on the Ptable axes, cite the figure or page on each table, and use modelDataMergeUnder only for data that is identical in both POHs. Where the model computes differently from the base methods in typeData.js, override them in the model file rather than adding cases to the base methods. Declare maxAltitude explicitly within the climb and cruise table extents. Add system, method and table tests with expected values taken from the POH examples, then run make <App>.test and make <App>.tableCoverage.

When the graphs and tables are in a checked Digitizer project, the ppdig-to-model skill starts the model file from it with ppdig model, as described in Making a model file.

Add an aircraft option

Add the <option> option to the V5 <App> app for serials <range>, from <POH supplement>. Decide whether it is optionOn or installedOn, and how it relates to existing options (optClass, includes, incompatibleWith, enabledBy). Test it by looking up values that differ from the base model through acData, not by checking options.installed.

Audit data against the POH

Check every table in <model file> against the POH at <path>, digit by digit. List each discrepancy with the POH page, the POH value and the code value. Don't change anything yet.

Review a change

Review the uncommitted changes against doc/dev/aiGuide.md. Look for correctness bugs, missed sibling apps, data that doesn't match the POH, model-specific cases added to base methods, missing tests and style violations. Verify each finding before reporting it, and rank them by severity.

Write or update documentation

Update the documentation in doc/ for <change>, following the Markdown style in doc/dev/style.md. Run make doc and make checkMdLinks.