Agentic Workflow Test Plan

This plan validates the outcome-first agentic workflow. It covers investigation, file structure, page assembly, registry injection, automated validation, and self-correction behavior.

1. Test Strategy

The workflow is considered healthy when a new agent can:

1. Classify the requested outcome.
2. Find the correct source-of-truth docs.
3. Identify exact files to read and change.
4. Build through the correct package, gallery, AppFlow, route, nav, token, or Code Connect path.
5. Run the validation commands appropriate to the touched files.
6. Stop and ask the user when approval is required.
7. Report blockers after three failed correction loops.

2. Documentation Link Tests

Run these checks after workflow docs change:

• docs/README.md links to:
  • docs/ai/project-context.md
  • docs/ai/operational-manifesto.md
  • docs/ai/workflow-contracts.md
  • docs/ai/workflow-test-plan.md
  • docs/ai/review-checklist.md
• docs/REPOSITORY_STRUCTURE.md documentation index includes the same AI workflow docs.
• The data-flow section in docs/REPOSITORY_STRUCTURE.md includes an agentic workflow flow.
• AI-facing docs do not instruct agents to use legacy stacks or non-Spring UI libraries.

3. Investigation Tests

Use these prompts as dry-run checks. The agent should answer with file targets, injection points, and validation commands before implementation.

Passing criteria:

• The agent names the outcome type.
• The agent lists exact file targets.
• The agent identifies whether user approval is required.
• The agent names the validation commands.

4. Contract Tests

For each implementation plan, verify:

• outcomeType is present.
• reuseDecision is one of reuse-existing, extend-existing, create-new, or assemble-only.
• filesToRead and filesToChange are explicit.
• registryUpdates names every export, route, nav, registry, Code Connect, or generated token artifact.
• validationCommands match the touched files.
• approvalRequired is true for new components, new tokens, new routes, structural deviations, and ambiguous UX states.

5. Component Workflow Tests

Run when packages/spring-ds-react/src/components/ changes.

Required checks:

• Component uses React, TypeScript, and Tailwind utilities.
• Styling maps to Spring DS tokens.
• Public component exports are added to packages/spring-ds-react/src/index.ts.
• Gallery docs import the component from @spring/ds-react.
• *.figma.tsx changes are parsed with Code Connect.

Commands:

npm run lint
npm run build
npm run code-connect:parse

npm run code-connect:parse is required only when Code Connect files change.

6. Gallery Page Workflow Tests

Run when apps/design-library/src/gallery/pages/, apps/design-library/src/app/library/, or libraryNav.ts changes.

Required checks:

• Route shell under src/app/library/ re-exports a gallery implementation.
• Gallery implementation lives under src/gallery/.
• libraryNav.ts is updated only for live pages.
• Placeholder-only pages remain hidden from navigation.
• Internal route links use Next.js primitives in app code.

Command:

npm run build

7. AppFlow Workflow Tests

Run when apps/design-library/src/gallery/page/appflow/ changes.

Required checks:

• Screen body is presentational and isolated from production data, analytics, database calls, and third-party business logic.
• Screen is imported into personalLoanFlow.ts.
• Registry entry includes Body, sourcePath, slug, status, summary, progress, and phase metadata.
• The expected route resolves under /library/page/appflow/personal-loan/<slug>.
• Preview behavior uses the existing AppFlow shell and registry.

Commands:

npm run build

For narrow visual-only work, a targeted manual browser run may replace the full manual QA run when documented in the handoff.

8. Token Workflow Tests

Run when design-tokens.mjs or generated token artifacts change.

Required checks:

• A token gap report exists for new visual values.
• New values follow existing token naming and semantic grouping.
• Generated CSS and sync manifest are intentionally updated.
• Consuming components use token names rather than raw values.
• Any active dev server is restarted before trusting local preview output.
• apps/design-library/.next is cleared before production build validation.

Commands:

npm run tokens:sync
rm -rf apps/design-library/.next
npm run lint
npm run build

lint and build are required when consuming component or gallery files also change.

9. Code Connect Tests

Run when any *.figma.tsx file changes.

Required checks:

• The mapping points to the correct code component or gallery pattern.
• Imports resolve through figma.config.json aliases.
• The file is only added when a Figma component mapping is part of the outcome.
• New input mappings live package-side under packages/spring-ds-react/src/components/inputs/.
• Existing navigations, overlays, and SpringSearchBar mappings remain gallery-side until a migration is planned.

Command:

npm run code-connect:parse

10. Documentation And Rule Tests

Run when docs/ or .cursor/rules/ changes.

Required checks:

• Long-form workflow guidance lives in docs/ai/.
• .cursor/rules/ stays short and executable.
• Docs and rules do not conflict on file paths, stack, or validation commands.
• Links from docs/README.md and docs/REPOSITORY_STRUCTURE.md are present.

Suggested validation:

• Read the changed docs from top to bottom.
• Search changed AI docs for stale legacy stack or non-Spring UI library instructions.
• Confirm the investigation path points to existing files.

11. Self-Correction Loop Tests

A validation failure must produce:

• Failed command.
• Affected file or likely file.
• Error summary.
• Required correction action.
• Current loop count.

Passing behavior:

• Attempts 1 and 2 may return to implementation with targeted corrections.
• Attempt 3 may run one final correction.
• After a third failed validation, the workflow stops and returns a blocker report.

Blocked report must include:

• Command that failed.
• Short stderr summary.
• Files involved.
• What was tried.
• Recommended user decision.

12. Resume Tests

Run when a workflow continues after interruption, a rejected plan, or a partially completed validation loop.

Required checks:

• The agent re-states WorkflowRunState.
• Approval status is visible or re-confirmed by the user.
• Loop count is preserved or reset with explanation.
• Files already changed are listed.
• Next action is explicit before implementation continues.
• Any persisted .spring/ state is treated as local runtime context, not source of truth.

13. Final Handoff Checklist

Before delivery, the Guardrail Critic confirms:

• Outcome type is named.
• Files changed are listed.
• Route or import path is provided when applicable.
• Registry, route, export, nav, Code Connect, or token injection is summarized.
• Validation commands are listed with pass, skip, or not-run status.
• Dirty-tree caveats are disclosed.
• Remaining risks are concise and actionable.