Index of every page on this site: llms.txt
All skills
a2ui-project avatar

/coding-principles

@6bf4cc2
by A2UIa2ui-project/a2ui18k stars
1,430
Run it yourself

Enforces engineering, architecture, public API, and code quality standards distilled from human reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint generation without code or PR changes.

  • 17 files
  • 75.1 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/a2ui-project/a2ui/coding-principles

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

subskillsswiftcoding-standards-and-testing.md

≈1.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Subskill: Swift Architecture, Coding Standards, Testing & Verification

Activation Criteria

Activate this subskill when:

  • Developing, refactoring, or reviewing any Swift code under swift/ or Package.swift.
  • Implementing state logic, JSON pointer evaluation, or SwiftUI component views.
  • Writing or modifying Swift unit tests.

1. Swift Target Architecture

The Swift implementation uses targets defined in root Package.swift:

  • A2UIJSON (core/Sources/A2UIJSON): Pure JSON Schema 2020-12 definitions and remote schema registry storage.
  • A2UICore (core/Sources/A2UICore): Stateful runtime engine managing MessageProcessor, DataModel, SurfaceGroupModel, pointer evaluation, and action routing.
  • BasicCatalog (core/Sources/BasicCatalog): Core schema definitions and function handlers for Basic Catalog components.
  • A2UISwiftUI (swiftui/Sources/A2UISwiftUI): SwiftUI adapter providing the root Surface view, recursive ComponentNodeView, and environment keys.
  • BasicCatalogSwiftUI (swiftui/Sources/BasicCatalog): Concrete SwiftUI view implementations conforming to ComponentImplementation.
  • A2UISampleClient (swift/sample): Interactive iOS Gallery application managed via Xcode project file.

2. Mandatory Coding Standards

All Swift code must strictly follow swift/CODING_STANDARDS.md and the Google Swift Style Guide:

  1. One primary type per file: Every class, struct, enum, and protocol must live in a dedicated file named after the type.
  2. 100-character line limit: No line of code, comment, docstring, or markdown may exceed 100 characters.
  3. 2-space indentation: Enforced by swift-format.
  4. Apache 2.0 copyright header: Required on every new .swift file:
    // Copyright 2024 Google LLC
    //
    // Licensed under the Apache License, Version 2.0 (the "License");
    // you may not use this file except in compliance with the License.
    // You may obtain a copy of the License at
    //
    //     https://www.apache.org/licenses/LICENSE-2.0
    //
    // Unless required by applicable law or agreed to in writing, software
    // distributed under the License is distributed on an "AS IS" BASIS,
    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    // See the License for the specific language governing permissions and
    // limitations under the License.
  5. Safe optional handling: Never use force-unwrapping (!) or forced tries (try!) on runtime or external data; use optional bindings (if let, guard let) or propagate throwing errors. Using try! or ! is permitted for hardcoded compile-time constants (e.g., static regular expressions or embedded JSON Schema literals) that can only fail due to a developer error in transcribing the static string.

3. Swift Testing Conventions

Tests use the native Swift Testing framework:

  • Import Testing instead of XCTest.
  • Annotate test functions with @Test.
  • Use #expect(...) for assertions.
  • In tests, replace force unwraps with try #require(...) to produce clean test failures instead of crashes.
  • Avoid @testable import. Test only the public API surface.
  • Use standard camelCase identifiers for test function names without backticks or spaces.

4. Verification Workflow

After making any code changes in swift/, run this verification sequence from the repository root:

  1. Auto-format code:
    swift-format format -i -r Package.swift swift/
  2. Lint check:
    swift-format lint -r Package.swift swift/
  3. Run unit tests:
    swift test
    Or run filtered tests during iterative development:
    swift test --filter A2UICoreTests
    swift test --filter A2UISwiftUITests
  4. Compile check:
    swift build

5. Integration with Repository Skills

  • Blueprint compliance: When updating models or schemas, check compliance with a2ui-blueprint-compliance.
  • Test quality: Verify assertion strength and boundary cases with a2ui-test-quality-check.
  • Documentation sync: Ensure documentation reflects code changes using a2ui-doc-sync-check.
  • Changelog updates: When changing public APIs or consumer-observable behavior in published Swift library products, update swift/CHANGELOG.md using update-changelog.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 6bf4cc2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
metadata
{
  "internal": true
}

README badge

README badge for a2ui-project/a2ui/coding-principles