Find the board. projects_list with method: list_projects for the owner. Set owner_type to user or org when you know it, to skip a lookup. The project_number from the result identifies the board in every later call.
Read the board's fields before anything else. projects_list with method: list_project_fields returns each field's id, name, type, and — for single-select fields — its valid option names. You cannot set a field correctly without this, and guessing an option name fails the call.
Read the items with their field values. projects_list with method: list_project_items returns titles only unless you pass field_names or fields. Passing neither is the most common reason a board looks empty of status.
Inspect a single item or view with projects_get when you need the full picture of one thing rather than a page of many.
Add work to the board. projects_write with method: add_project_item, item_type of issue or pull_request, and the item_owner, item_repo and issue or pull request number. Adding an item that is already on the board is not a way to move it.
Update field values. Use method: update_project_items for a batch — one field and value applied across up to fifty items — and method: update_project_item for a single item. Prefer the batch call over repeating the single one; it is one decision, recorded once.
Post a status update with method: create_project_status_update when the request is to communicate progress rather than to move items.

Reading and reporting a complete board

Read field IDs, types and option names first. Use the exact returned names; map words such as "sprint" to an iteration field only if that field actually exists.
Reflect the requested content type in filters: "open issues" is state:open is:issue; "merged pull requests" is state:merged is:pr. Keep mixed content when the request is about all items. Use wildcards for label or milestone names where repository naming varies.
Follow pageInfo.endCursor with after while pageInfo.hasNextPage is true. Keep the query, requested fields and page size unchanged between pages. Use before only when explicitly navigating backwards.
Count the returned items after full pagination, not field objects or nested arrays. A list request needs the items and total; summarize only when asked to analyze or summarize. Say which pages or fields could not be retrieved.
When creating a project, pass the owner's type and title and use the returned project number in later calls, not its node ID. For iteration fields, use field_name, iteration_duration in days, and start_date as YYYY-MM-DD. Supply explicit iterations only for varying durations, breaks or custom titles.
Inspect views before changing them. visible_fields is create-only and is not available for roadmap views.

Decision points

Is the board the source of truth, or a mirror? If items are meant to track repository issues, add the issues rather than creating standalone items, so state stays connected.
Batch or single. More than one item taking the same value is a batch. Different values are separate calls, and a long list of separate calls is worth pausing on — it usually means the field or the plan needs rethinking.
Move or close. An item that will not be worked belongs in whichever closing status the board defines, not deleted. Deletion loses the history of having planned it.
New field or existing. Prefer an existing field. create_iteration_field adds durable structure to someone else's board and should be proposed, not assumed.

Fields that matter

field_option_name against a raw option id — the name is checked before the call goes out, so it fails clearly rather than silently writing the wrong value.
updated_field — either {name, value} or {id, value}. A null value clears the field, which is different from setting it to an empty string.
project_number against the project node id — the number is what these tools take.
owner_type — omitting it costs a lookup, and gets it wrong when a user and an organisation share a name.
field_names on a list — without it you get titles and nothing else.

Confirm before changing anything

A project board is shared state that people plan against, and these calls have no undo.

delete_project_item and delete_project_view remove things others rely on. Confirm by listing the exact item or view titles first.
create_project and create_iteration_field create durable structure. Ask before either; do not create a board because none was found.
A batch update touching many items should be presented as a list of item titles and the value they will all receive, and agreed before it is sent.

Empty and failure cases

No projects for the owner — say so and stop. Do not create one.
The board has no items — report an empty board rather than an error; a new board is a normal state.
A field name does not match — list the available fields and ask. Never substitute the closest looking option name.
A batch update partially fails — report which items took the value and which did not, then stop. A board that is half updated and described as done is worse than one that is untouched.

project-planning

Planning work on a project board

Sequence