scout_annotations

Annotation library for the Scout Application Capability Intelligence Platform.

Annotate your Flutter screens and services with @Capability, @Workflow, @Permission, @FeatureFlag, and @Owner to enable Scout's compile-time capability graph generation — zero runtime dependencies, safe to include in production code.

One package or two? If you only need annotations, use scout_annotations. If you also want to read scout.manifest.json programmatically (e.g. in tests or CLI tools), use scout instead — it re-exports all annotations plus a typed ScoutManifest model.

What is Scout?

Scout transforms Flutter apps into machine-readable capability graphs consumed by AI systems (Claude Code, Cursor, Windsurf, in-app copilots) at compile time. Instead of an AI having to scan thousands of lines of source to understand what your app can do, it reads a single scout.manifest.json — a structured map of every capability, who can use it, and what API it calls.

scout_annotations is the developer-facing surface of Scout: the annotations you place on your screens and services. Everything else is generated from them.

Quick start

# pubspec.yaml
dependencies:
  scout_annotations: ^0.1.0

import 'package:scout_annotations/scout_annotations.dart';

@Capability(
  id: 'view_attendance',
  label: 'View Attendance',
  category: 'Academic',
  description: 'Shows subject-wise attendance summary for the selected semester.',
  permissions: ['attendance:read'],
  preconditions: ['authenticated_user'],
  relatedCapabilities: ['download_report_card'],
  analyticsEvent: 'attendance_viewed',
  owner: 'academic-team',
  gdpr: GdprClass.none,
)
class AttendanceScreen extends StatelessWidget {
  // ...
}

Run dart run build_runner build (with scout_builder configured) to generate scout.manifest.json.

Annotations reference

`@Capability`

The core annotation. Place on a screen widget class or a service method.

Field	Type	Default	Description
`id`	`String`	required	Unique snake_case identifier. Convention: `verb_noun` (e.g. `mark_attendance`)
`label`	`String`	required	Human-readable display name
`category`	`String`	required	Functional grouping (e.g. `'Attendance Management'`)
`description`	`String?`	—	Plain-English description of what the user can accomplish. Used by AI systems to route requests
`permissions`	`List<String>`	`[]`	Permission IDs required. Convention: `resource:action` (e.g. `attendance:write`)
`preconditions`	`List<String>`	`[]`	State keys that must be true before invoking (e.g. `authenticated_user`)
`relatedCapabilities`	`List<String>`	`[]`	IDs of related capabilities for AI navigation hints
`analyticsEvent`	`String?`	—	Analytics event emitted when this capability is used
`owner`	`String?`	—	Team or individual responsible. Used by `scout diff` to notify owners of breaking changes
`gdpr`	`GdprClass`	`none`	GDPR data classification. `scout audit gdpr` uses this for Article 30 records
`offlineCapable`	`bool`	`false`	Whether this capability works without a network connection

`@Permission`

Declares a named permission centrally so Scout can build a complete permission registry and validate that every @Capability(permissions: [...]) entry references a declared permission.

@Permission(
  id: 'attendance:write',
  label: 'Write Attendance',
  description: 'Allows recording and updating attendance records.',
  roles: ['teacher', 'admin'],
)
class AttendanceWritePermission {}

Field	Type	Default	Description
`id`	`String`	required	Unique identifier. Convention: `resource:action`
`label`	`String`	required	Human-readable name for dashboards and audit reports
`description`	`String?`	—	What this permission grants
`roles`	`List<String>`	`[]`	Roles that hold this permission by default

`@Workflow`

Groups related capabilities into a named multi-step flow that AI systems can use to guide users through complex operations.

@Workflow(
  id: 'fee_payment_workflow',
  label: 'Pay Fees',
  description: 'End-to-end flow for viewing and paying outstanding fees.',
  steps: [
    WorkflowStep(order: 1, capabilityId: 'view_fee_structure'),
    WorkflowStep(order: 2, capabilityId: 'view_fee_dues'),
    WorkflowStep(order: 3, capabilityId: 'pay_fees_online'),
    WorkflowStep(order: 4, capabilityId: 'download_fee_receipt', optional: true),
  ],
)
class FeePaymentFlow {}

Field	Type	Default	Description
`id`	`String`	required	Unique snake_case identifier
`label`	`String`	required	Human-readable name
`description`	`String?`	—	What this workflow accomplishes
`steps`	`List<WorkflowStep>`	required	Ordered capability sequence

WorkflowStep fields: order (int, 1-based), capabilityId (String), description (String?, step-specific override), optional (bool, default false).

`@FeatureFlag`

Marks a screen or capability as gated by a feature flag. Scout records the flag in the manifest so scout serve can report which capabilities are currently enabled.

@FeatureFlag(
  id: 'new_attendance_ui',
  label: 'New Attendance UI',
  description: 'Redesigned attendance marking flow with bulk selection.',
  defaultValue: false,
  owner: 'attendance-team',
)
@Capability(id: 'mark_attendance', label: 'Mark Attendance', category: 'Attendance')
class MarkAttendanceScreen extends StatelessWidget { ... }

Field	Type	Default	Description
`id`	`String`	required	Unique snake_case identifier
`label`	`String`	required	Human-readable name
`description`	`String?`	—	What this flag enables
`defaultValue`	`bool`	`false`	Default when flag backend is unavailable
`owner`	`String?`	—	Responsible team/individual

`@Owner`

Declares team or individual ownership for a screen, service, or feature module. Lightweight alternative to the owner field in @Capability — useful when you want ownership without a full capability declaration.

@Owner('payments-team')
class CheckoutScreen extends StatelessWidget { ... }

@Owner('alice@example.com')
class ExperimentalFeatureScreen extends StatelessWidget { ... }

scout diff uses ownership to notify the right team when a breaking change is detected.

`GdprClass`

Enum for GDPR data classification used in @Capability(gdpr: ...).

Value	Meaning
`GdprClass.none`	Capability does not access personal data
`GdprClass.personal`	Accesses personal data (name, email, address, etc.)
`GdprClass.sensitive`	Accesses special-category data (health, biometrics, etc.)

scout audit gdpr uses this classification to produce GDPR Article 30 Data Processing Activity records automatically.

ID naming convention

Capability IDs must be globally unique within the app and follow verb_noun snake_case:

view_attendance      ✓
mark_attendance      ✓
pay_fees_online      ✓
download_report_card ✓

ViewAttendance       ✗  (PascalCase)
attendance           ✗  (no verb)
view-attendance      ✗  (kebab-case)

Part of Scout

scout_annotations is the annotation layer of the Scout platform:

scout_annotations    ← this package (zero dependencies)
      ↓
scout_builder        ← build_runner plugin, produces scout.manifest.json
      ↓
scout_cli            ← `scout scan`, `scout validate`, `scout diff`, `scout audit`
scout_mcp            ← MCP server + REST API for Claude Code / Cursor / Windsurf

See github.com/runo-ai/scout for the full platform.

License

MIT