Operational Manifesto: Outcome-First Agentic Workflow

This document is the primary operating model for AI-assisted design-to-code work in the Spring Design Library. It defines how agents classify outcomes, choose file targets, build pages, inject components, validate changes, and hand off work for review.

The workflow is outcome-first: every request must name the intended result before any implementation begins.

1. Operating Principles

1. Outcome before code. Classify the work as a component, gallery page, AppFlow screen, static page, token change, icon change, or documentation change before touching files.
2. Reuse before creation. Search existing package exports, gallery pages, tokens, and AppFlow registries before proposing new files.
3. Plan before implementation. Stop for user approval when structure, file placement, new tokens, new components, or route behavior is uncertain.
4. Gallery as source of truth. The design library route under /library/* is the visual handoff surface for page and AppFlow work.
5. Tokens are mandatory. No raw hex, arbitrary spacing, or unregistered visual values unless a token gap is approved and synced.
6. Validation closes the loop. Every output must name the commands or checks that prove the workflow succeeded.
7. Rules stay executable. Long explanations belong in docs/ai/; .cursor/rules/ should stay short and enforceable.

2. Outcome Types

Outcome A: Reusable Design System Component

Use this when the result should be imported from @spring/ds-react.

Required structure:

Validation:

• npm run lint
• npm run build
• npm run code-connect:parse when *.figma.tsx files are touched

Outcome B: Gallery Documentation Page

Use this when documenting or demonstrating existing design system behavior.

Required structure:

Rules:

• Import reusable UI from @spring/ds-react.
• Do not define product primitives inside gallery pages.
• Keep route files thin; page logic belongs in src/gallery/.
• Do not add placeholder-only pages to navigation.

Validation:

• Route shell exists and imports the gallery implementation.
• libraryNav.ts points to the route only when the page is live.
• npm run build

Outcome C: AppFlow Screen

Use this for personal loan flow screens and step previews.

Required structure:

Rules:

• Keep screens presentational. No production API calls, analytics, database access, or third-party business logic.
• Chrome, progress, footer, and route framing belong to the existing AppFlow shell.
• Register Body, status, slug, path, summary, progress, and sourcePath consistently.
• The final handoff must include the expected /library/page/appflow/personal-loan/<slug> route.

Validation:

• personalLoanFlow.ts imports and registers the screen.
• The dynamic route can resolve the slug.
• npm run build

Outcome D: Static Design Library Page

Use this for informational or foundation pages that are not reusable components and not AppFlow steps.

Required structure:

Rules:

• Prefer the existing gallery layout primitives.
• Keep routes thin and implementations in src/gallery/.
• Use a 1200px informational grid unless the request is explicitly an AppFlow-style page.

Validation:

• Route shell exists.
• Navigation is live only when content is complete.
• npm run build

Outcome E: Token Or Foundation Change

Use this when the visual system itself changes.

Required structure:

Rules:

• New visual values require an approved token gap.
• Run token sync after changing token source.
• Follow token names already used by the package and gallery.
• Restart any running dev server after token sync before trusting the local preview.
• Clear apps/design-library/.next before production build validation for token changes.

Validation:

• npm run tokens:sync
• rm -rf apps/design-library/.next
• npm run lint and npm run build when consuming files also change

Outcome F: Icon Change

Use this when adding or regenerating Spring icon components.

Required structure:

Rules:

• Prefer npm run icons:sync for Figma-sourced icon changes.
• Do not hand-edit large generated icon sets unless the change is intentionally scoped.
• Update gallery icon metadata only when the displayed categories or names change.

Validation:

• npm run icons:sync when pulling from Figma
• npm run build when consumed by the gallery

Outcome G: Documentation Or Rule Change

Use this for repo guidance, AI workflow, onboarding, or rule updates.

Required structure:

Rules:

• docs/ai/operational-manifesto.md owns workflow narrative.
• docs/ai/workflow-contracts.md owns file placement and output contracts.
• docs/ai/workflow-test-plan.md owns validation strategy.
• .cursor/rules/ should summarize stable behavior, not duplicate long docs.

Validation:

• Docs are linked from docs/README.md and docs/REPOSITORY_STRUCTURE.md.
• No legacy stack or non-Spring UI library instructions remain in AI-facing workflow docs.

3. Multi-Agent Model

The workflow uses five roles. A single AI may play multiple roles, but the responsibilities must stay distinct.

1. Workflow Conductor

Owns intake, outcome classification, agent selection, user approval gates, loop limits, and final handoff.

Outputs:

• WorkflowRunState
• approved BuildPlan
• final handoff summary

Must not:

• Skip required user validation.
• Hide validation failures.
• Revert unrelated user changes.

2. Design & Token Analyst

Reads Figma/MCP context, screenshots, user instructions, existing token files, and visual examples. Maps raw design values to project tokens or reports gaps.

Outputs:

• NormalizedDesignTree
• TokenGapReport

Must not:

• Write component syntax.
• Add raw styling values without a token decision.

3. Structure & Reuse Architect

Determines whether the request should reuse, extend, create, or assemble. Audits public exports, route shells, navigation, and registries before recommending files.

Outputs:

• AgenticImplementationPlan
• file map
• registry injection plan

Must not:

• Create a new component when an existing exported component satisfies the outcome.
• Route AppFlow work into reserved package folders when the live implementation belongs in the gallery app.

4. Implementation Builder

Builds only the approved outcome and updates the required injection points.

Outputs:

• component/page/screen patch set
• route shell changes
• export, nav, registry, Code Connect, or token sync changes when required

Must not:

• Put page logic inside thin route shells.
• Put production API or database logic inside gallery or AppFlow previews.
• Modify unrelated files for cleanup.

5. Guardrail Critic

Runs validation, classifies failures, gives correction instructions, and blocks after three failed correction loops.

Outputs:

• ValidationApprovalLog
• BlockedValidationReport

Must not:

• Mark work complete without naming validation coverage.
• Continue self-correction indefinitely.

4. Deterministic Workflow

flowchart TD
  intake[InboundRequest] --> classify[ClassifyTaskType]
  classify --> outcome[SelectOutcomeType]
  outcome --> contextCheck[RequiredContextCheck]
  contextCheck -->|"missing critical context"| askUser[AskUserForValidation]
  contextCheck -->|"context complete"| investigate[InvestigateExistingStructure]
  investigate --> normalize[TokenAndDesignNormalization]
  normalize --> plan[BuildPlanAndFileMap]
  plan --> planGate[HumanPlanValidation]
  planGate -->|"changes requested"| plan
  planGate -->|"approved"| build[BuildOutcomeFiles]
  build --> inject[InjectRoutesRegistriesExports]
  inject --> validate[GuardrailValidation]
  validate -->|"fail under loop limit"| correct[CorrectionInstructions]
  correct --> build
  validate -->|"fail after loop limit"| blocked[UserEscalation]
  validate -->|"pass"| handoff[DeveloperHandoff]

5. Investigation Order

Before building, inspect in this order:

1. docs/ai/project-context.md - classify the task and required intake.
2. docs/ai/operational-manifesto.md - choose the workflow.
3. docs/ai/workflow-contracts.md - confirm file targets and injection points.
4. docs/REPOSITORY_STRUCTURE.md - use broader repo context when needed.
5. Nearby examples in packages/spring-ds-react/src/components/ or apps/design-library/src/gallery/.
6. docs/ai/review-checklist.md - run the final quality gate before handoff.

6. Core Guardrails

• Human validation gate: Stop after structural planning when the implementation path, token additions, or new component creation needs user approval.
• Token guardrail: No raw hex, arbitrary spacing, or unregistered styling unless approved through a token gap.
• File boundary guardrail: Components stay in packages/spring-ds-react; gallery docs and AppFlow screens stay in apps/design-library/src/gallery; routes stay under apps/design-library/src/app/library.
• Reuse-first guardrail: Audit existing exports and nearby examples before adding files.
• Server-first guardrail: Default to Server Components. Add 'use client' only for hooks, events, lifecycle, or browser APIs.
• Registry guardrail: Update all required injection points for the outcome: src/index.ts, route shell, libraryNav.ts, personalLoanFlow.ts, Code Connect, or token generated artifacts.
• Placeholder guardrail: Do not add placeholder-only pages to navigation.
• Self-correction guardrail: Run at most three correction loops before pausing with a blocker report.
• Dirty-tree guardrail: Do not revert unrelated user changes. Report any pre-existing modified files that affect validation confidence.

7. Self-Correction Protocol

When validation fails, the Guardrail Critic must produce a targeted correction instruction:

### System Intervention: Validation Failed

#### Failure Context
- Command: {COMMAND}
- File: {FILE_PATH}
- Error: {SUMMARY}

#### Required Correction
- Fix only the files related to the approved outcome.
- Preserve the functional and visual requirements.
- Do not introduce raw styling values or unrelated refactors.
- Re-run the failed validation command.

#### Loop Count
Attempt {CURRENT_ATTEMPT} of 3.

If the third attempt fails, stop and return a BlockedValidationReport with the command, error summary, affected files, and recommended user decision.

8. Developer Handoff

A completed workflow must provide:

• Outcome type.
• Current WorkflowRunState, including phase, approval status, loop count, files changed, and next action if work is continuing.
• Files changed.
• Route or import path to use.
• Registry/export/nav injection summary.
• Validation commands run and results.
• Known risks, skipped validations, or dirty-tree caveats.

If a workflow resumes after interruption, re-state the latest known WorkflowRunState and confirm user approval before continuing any implementation that depends on prior approval.

For gallery and AppFlow work, the /library/* route is the visual source of truth. Product developers should import verified presentational components and bind production data, tracking, and business logic outside the gallery.