local-dev

# Local development Use this skill for repository development changes. Read the root and applicable nested `AGENTS.md`, the owning current reference, and relevant source before editing. Keep work within the approved platform scope and preserve unrelated work. Run repository commands from its root; bundled `./` paths below are relative to this skill directory. No global skill installation is required. Use explicit dependency records and focused factories when extracting behavior. The [fixture and scenario conventions](../../../docs/testing/fixtures-and-scenarios.md) apply the same composition rules to test infrastructure. ## HARD REQUIREMENT: OPEN-SOURCE CONTENT THIS IS AN OPEN-SOURCE REPOSITORY. NEVER MENTION INTERNAL CODE NAMES OR CORPORATE INTERNAL NAMES IN CODE, COMMENTS, DOCUMENTATION, EXAMPLES, TEST FIXTURES, GENERATED ARTIFACTS, COMMIT MESSAGES, OR PULL REQUEST CONTENT. THIS REPOSITORY SHOULD NEVER CONTAIN CORPORATE INTERNAL NAMES. USE PUBLIC PRODUCT NAMES OR NEUTRAL, DESCRIPTIVE TERMS INSTEAD. CHECK THE ENTIRE PROPOSED CHANGE BEFORE HANDOFF OR PUBLICATION AND REMOVE ANY SUCH REFERENCES. DO NOT COPY INTERNAL CONTEXT INTO THIS REPOSITORY, EVEN AS BACKGROUND OR PROVENANCE. ## HARD REQUIREMENT: KEEP IMPLEMENTATION-SPECIFIC BEHAVIOR OUT OF THE CORE IMPLEMENTATION-SPECIFIC FUNCTIONALITY MUST LIVE IN DRIVERS OR BACKENDS, NEVER BE HARDCODED INTO THE PLATFORM CORE. CORE CODE MUST DEPEND ON PLATFORM CONTRACTS, NOT SPECIAL CASES FOR A PARTICULAR IMPLEMENTATION, VENDOR, OR DEPLOYMENT. EXTEND THE OWNING DRIVER OR BACKEND CONTRACT WHEN NECESSARY; DO NOT BYPASS IT WITH IMPLEMENTATION-SPECIFIC BRANCHES, DEFAULTS, OR DIRECT CALLS IN THE CORE. IF A DEVELOPER OR AGENT PROPOSES OR INTRODUCES SUCH A VIOLATION, CALL IT OUT EXPLICITLY AND STOP THE SESSION'S IMPLEMENTATION WORK. IDENTIFY THE OFFENDING CODE OR DESIGN, EXPLAIN THE OWNERSHIP BOUNDARY IT VIOLATES, AND ASK FOR A DESIGN CHANGE THAT MOVES THE BEHAVIOR INTO THE APPROPRIATE DRIVER OR BACKEND. DO NOT IMPLEMENT, COMMIT, OR PUBLISH THE VIOLATING APPROACH. RESUME ONLY AFTER THE REVISED DESIGN RESOLVES THE BOUNDARY VIOLATION AND THE USER APPROVES IT. ## Workflow 1. Identify the user-visible outcome, owning primitive, real caller, and affected lifecycle. Inspect the diff and existing `docs/flows/` before choosing docs. 2. Implement the smallest complete change through the owning contract. Preserve the repository's authorization, state, and ownership invariants. 3. Apply the flow-doc trigger below. For a qualifying change, read [the workflow](./references/flow-doc/workflow.md) and update the existing behavior flow in the same change. Use [the template](./references/flow-doc/template.md) only when no existing document owns that flow. Use $mermaid-diagrams for diagram semantics. For these flow docs, override its notation defaults: start the Mermaid block with `graph TD`, omit Mermaid YAML frontmatter, and retain this workflow's required sections so the bundled validator accepts it. 4. Use $technical-writing when creating, editing, or reviewing documentation. Update affected current references, guides, and navigation. Preserve historical specs and user-owned Manual Notes. Do not create a second source of truth. 5. Use $enterprise-testing to select proportional checks and satisfy repository integration requirements for new functionality. Follow [Add integration tests](#add-integration-tests) when adding coverage. For instruction-only changes, check docs, links, skill resources, and any bundled executable; do not run product runtime suites solely for prose. Never run `npm run precommit`. When changing a default image version, source pin, or bundled runtime version, always complete [image version verification](./references/image-version-verification.md) before merging. A green ordinary PR check does not replace this workflow. 6. When publication is authorized, follow the [PR policy](../../../CONTRIBUTING.md#prepare-a-pull-request). Verify identity, repository URLs, and the push destination. Preserve existing remotes; their names do not establish ownership. Preserve the head repository and branch when updating an assigned existing PR. Use the verified base for branch comparisons and reviews. Complete the [PR readiness checklist](./references/pr-readiness.md) before requesting review and recheck its merge requirements at the final PR head. 7. Report changed behavior, the flow updated (or a short reason none is needed), checks run, and remaining verification gaps. Do not equate a structural doc check with proof of runtime behavior. ## Add integration tests Register new integration scenarios in the QA matrix: 1. Extend the supported Agent workflow in `tests/integration/qa-matrix-real.test.mjs`. Exercise real callers and dependencies, including meaningful failure cases. Use owned disposable fixtures and cleanup. 2. Register the scenario, applicable presets, and required inputs in `tests/helpers/qa-selection.mjs`. Update [QA manifest](../../../scripts/ci/test-suites/qa-matrix.json) for new inputs, files, or preparation; update [hosted credential setup](../../../scripts/ci/qa-matrix-credentials.mjs) when credentials change. 3. For scenarios that must run automatically on PRs, update `.github/workflows/qa-advisory.yml`. Add the selector to `OCC_TEST_QA_SCENARIOS` with applicable presets/installations, or add a job for a separate lane. Preserve trusted-PR eligibility and scope credentials to the job's environment. 4. Update the [QA scenarios and PR coverage](../../../docs/testing/ci.md#qa-matrix). Follow the [fixture conventions](../../../docs/testing/fixtures-and-scenarios.md) and run the selected scenario with its required prerequisites. Verify passing cases without skips and complete run-owned cleanup; report any missing proof. ## When a flow doc is required A change is **non-trivial** when it adds or materially changes a runtime path, state transition, ownership or authorization boundary, persistence behavior, external integration, asynchronous handoff, or consequential decision/failure handling. This includes fixes and refactors that change how these work even if an API signature stays the same. Size and line count do not decide the trigger: a one-line authorization or retry-policy change can qualify. Create or update a source-backed flow doc for every such change. Cover the changed path and its meaningful boundaries, not every touched file. Prefer a focused update to an existing behavior-named document under `docs/flows/`; create a new one only for a distinct runtime flow without an existing owner. Link adjacent phases instead of duplicating their traces. Typos, formatting, copy/link corrections, comment-only edits, behavior-preserving local renames, and test-only or instruction-only maintenance do not require a new flow doc when they leave the documented lifecycle accurate. Correct stale source pointers or flow claims if those edits invalidate them. An explicit request for a flow doc still applies. Do not manufacture runtime documentation for an instruction change merely to satisfy this skill. ## Resources and validation - [Image version verification](./references/image-version-verification.md): mandatory native image checks before merging version changes and publication follow-through. - [PR readiness checklist](./references/pr-readiness.md): evidence and handoff requirements before review and merge. - [Flow workflow](./references/flow-doc/workflow.md): source gathering, sections, preservation, provenance, and the required validator command. - [Flow template](./references/flow-doc/template.md): scaffold for new flow docs. - [Validator](./scripts/validate_flow_doc.py): portable structural checks using Python 3.10+ and only its standard library; no package installation needed. Flow guidance and validator are adapted from Specy 2.0.0. The repository owns this adaptation; it has no dependency on personal skills, memory stores, or session lookup tools. See the developer-skills catalog for provenance.