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.

@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 {}

@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 {}

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 { ... }

@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: ...).

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