IDE + Machine Setup
    ↓
Product Discovery
    ↓
Product Specification
    ↓
Terminology
    ↓
Technology Freshness Audit
    ↓
Architecture
    ↓
Repository Bootstrap
    ↓
Agent Constitution
    ↓
Skills + Rules
    ↓
Design Philosophy
    ↓
Design Tokens
    ↓
HQ UI Reference Generation
    ↓
Component Laboratory
    ↓
Application Shell
    ↓
Contracts + Dependency Readiness
    ↓
Implementation
    ↓
Testing + Security + Accessibility
    ↓
CI/CD
    ↓
Staging
    ↓
Production
    ↓
Monitor / Debug / Upgrade
    ↺

Product intent
+ UX model
+ visual system
+ architecture
+ code
+ tests
+ security
+ deployment
+ operational feedback

Human prompt → AI → code → done

Human intent
    ↓
Project context
    ↓
Rules
    ↓
Specialized skill
    ↓
Current documentation
    ↓
Canonical examples
    ↓
AI implementation
    ↓
Automated checks
    ↓
Independent review
    ↓
Human approval

G0 Idea Gate
G1 Product Gate
G2 Technology Gate
G3 Architecture Gate
G4 Design Gate
G5 Foundation Gate
G6 Contract Gate
G7 Feature Gate
G8 Quality Gate
G9 Release Gate
G10 Production Gate
G11 Operations Gate

Instructions
+ Context
+ Tools
+ Model reasoning
+ Repository state
+ Feedback

docs/INDEX.md

Task type                 Read these first
-------------------------------------------------------
UI                        design + UX + motion + UI refs
API                       architecture + contracts + security
Database                  architecture + data model + migration policy
Authentication            security + architecture + contracts
Production bug           operations + architecture + incident process
Dependency update        technology policy + dependency policy

1. Explicit product requirements
2. Approved product decisions
3. Approved design references
4. Current official technology documentation
5. Project architecture
6. Project design system
7. Canonical implementation examples
8. External standards
9. General model knowledge
10. AI preference / aesthetic intuition

Product behavior     → Product Spec
Terminology          → Product Terminology
Visual appearance    → Approved Design Reference
Exact tokens         → Design Tokens
Architecture         → Architecture document + ADRs
API boundary         → API Contract
Database structure   → Data Model + migrations
Security             → Security Policy + automated checks
Accessibility        → Accessibility Policy + tests
Current API syntax   → Official current docs

docs/
├── 00-project-context.md
├── 01-product-spec.md
├── 02-product-terminology.md
└── adr/

You are the Product Discovery and Specification Interviewer.

Your job is NOT to code, architect, or design the interface yet.
Your job is to interrogate me until the product is sufficiently
specified for implementation.

Be rigorous and persistent. Do not accept vague answers when they
could affect product behavior, architecture, UX, security, data,
permissions, cost, reliability, or future maintenance.

Work through these areas:

1. Product vision
2. Problem statement
3. Target users
4. Secondary users
5. User roles and permissions
6. User environment and devices
7. Jobs-to-be-done
8. Primary user journeys
9. Secondary journeys
10. Core features
11. Non-goals
12. Business rules
13. Data entities
14. Data ownership
15. State transitions
16. Integrations
17. Notifications
18. Search/filter/sort behavior
19. Error behavior
20. Empty/loading/success states
21. Accessibility requirements
22. Security requirements
23. Performance requirements
24. Reliability requirements
25. Analytics requirements
26. Administration
27. Compliance requirements
28. Deployment assumptions
29. Operational requirements
30. Future extensibility

Rules:
- Do not ask everything at once.
- Ask the next most valuable questions.
- When my answer is ambiguous, ask follow-up questions.
- Detect contradictions with earlier answers.
- Tell me when two answers conflict.
- Challenge assumptions respectfully.
- Do not silently decide business behavior for me.
- Maintain an explicit unresolved-question list.
- Maintain an explicit decision log.
- Mark each item as requirement, preference, assumption, constraint,
  decision, or risk.
- Continue until all material questions are resolved or explicitly
  accepted as risk.

At the end of every round provide only:
1. What is now decided
2. What remains ambiguous
3. The next questions

Do not produce application code during this phase.
Do not declare the process finished prematurely.

You are the Product Specification Finalizer.

Using the completed interview:

1. Check for contradictions.
2. Check for missing material requirements.
3. Check business rules for undefined states.
4. Check roles and permissions for gaps.
5. Check core workflows for missing failure paths.
6. Check data ownership and lifecycle.
7. Check integrations and external dependencies.
8. Check non-functional requirements.
9. Check accessibility and security.
10. Check operational requirements.

Classify every statement as:
- requirement
- preference
- assumption
- constraint
- decision
- risk
- non-goal

Do not silently fill gaps.

If material unknowns remain, output an unresolved-question list and
STOP before finalization.

If complete, generate:
- 00-project-context.md
- 01-product-spec.md
- 02-product-terminology.md
- ADR candidates
- acceptance-criteria summary
- open-risk register

Then run a consistency audit across all generated documents.

# Project Context

## Product

## One-Sentence Definition

## Why It Exists

## Problem

## Primary Users

## Secondary Users

## User Environment

## Product Personality

## Desired Feel

## Must Never Feel Like

## Core User Jobs

## Primary Workflows

## Business Context

## Competitive Context

## Non-Goals

## Constraints

## Success Definition

## Known Risks

# Product Specification

## 1. Vision
## 2. Problem
## 3. Users
## 4. Roles
## 5. User Journeys
## 6. Features
## 7. Functional Requirements
## 8. Business Rules
## 9. Data Requirements
## 10. Permissions
## 11. Integrations
## 12. Notifications
## 13. Search / Filtering / Sorting
## 14. Error / Loading / Empty States
## 15. Non-Functional Requirements
## 16. Accessibility
## 17. Security
## 18. Performance
## 19. Reliability
## 20. Analytics
## 21. Administration
## 22. Deployment Constraints
## 23. Non-Goals
## 24. Acceptance Criteria
## 25. Risks
## 26. Future Considerations

docs/02-product-terminology.md

Term
Market meaning
Our project meaning
Why this meaning is used
Example
Non-example
Related terms

Module
Feature
Capability
Component
Primitive
Pattern
Shell
Scaffold
Controller
Service
Repository
Use Case
Adapter
Contract
Provider
Integration
Reference
Token
Skill
Rule
Decision
ADR
Source of Truth
Task Packet
Change Packet
Dependency
Hotspot
Release
Incident

Module
= a bounded business capability with owned code/data behavior.

Feature
= a user-visible or business-visible capability inside a module.

Controller
= transport/interface layer; does not contain business rules.

Service
= business/application behavior; does not directly manage HTTP concerns.

Repository
= persistence boundary; does not decide product policy.

Primitive
= low-level reusable UI behavior.

Component
= reusable user-interface implementation.

Shell
= shared frame around a class of pages.

Reference
= approved visual source used to evaluate implementation fidelity.

Who?
What?
Why?
When?
What is success?
What is failure?
What is the edge case?

### AC-001

Given:
When:
Then:

Edge cases:

Security considerations:

Accessibility considerations:

Observability:

 docs/03-technology-policy.md

You are the project's Technology Researcher and Upgrade Analyst.

Your task is to determine the current production-safe technology
baseline for this project.

Do not rely on model memory for anything that can change.

For every major technology or dependency:

1. Identify the currently supported stable release.
2. Verify official support or LTS status.
3. Read the official installation documentation.
4. Read official migration/breaking-change documentation.
5. Identify deprecated APIs.
6. Identify the current recommended architecture.
7. Identify official security guidance.
8. Identify runtime compatibility requirements.
9. Determine whether the newest release is stable, RC, beta, canary,
   nightly, or experimental.
10. Determine whether the project should use it now.
11. Record the exact official sources.
12. Record known migration work.
13. Record upgrade risk.

Do not choose a dependency merely because its version number is higher.
Prefer the latest stable, production-supported, officially recommended
version compatible with the project.

Output:
- Technology Decision Record for every major dependency
- baseline version table
- deprecated-pattern blacklist
- upgrade watchlist
- unresolved compatibility questions

Do not modify application code during this phase.

Technology Adapter
├── CLI initialization command
├── version pinning mechanism
├── folder conventions
├── build command
├── test command
├── lint command
├── type-check command
├── local development command
├── database migration command
├── production build command
├── deployment command
└── official documentation links

Operating system
Shell
Git
Runtime
Package manager/build tool
Project CLI(s)
Editor/IDE
GitHub/GitLab/etc. CLI if used
Credential manager
Environment variable strategy
Optional database client
Optional API testing client

runtime version file
package-manager version field
lockfile
CLI/version notes

"Install whatever is newest"

Act as the Developer Environment Engineer.

Inspect the target operating system and repository requirements.

Determine:
- required runtime
- exact supported runtime line
- package manager
- required CLI tools
- optional tools
- authentication requirements
- environment variables
- local service requirements
- database requirements
- test prerequisites
- browser prerequisites

Research current official installation instructions for every tool
that has version-sensitive installation steps.

Then produce a beginner-safe setup guide with:
1. exact installation commands
2. verification commands
3. expected output
4. common failure modes
5. troubleshooting
6. repository setup commands
7. first successful test

Do not assume Docker.
Do not assume a specific operating system unless detected.
Do not install unnecessary global packages.

setup doctor

runtime version
package manager version
Git
CLI tools
environment files
required ports/services
lockfile integrity
basic build

git config user.name
git config user.email

protected main
PR required
required CI checks
required review(s)
CODEOWNERS where useful
secret scanning
dependency/security checks
merge queue where appropriate

<type>(<scope>): <description>

feat(auth): add session rotation
fix(users): prevent unauthorized profile update
refactor(ui): consolidate form primitives
test(events): add registration contract tests
chore(deps): update supported runtime

project/
├── AGENTS.md
├── README.md
├── CONTRIBUTING.md
├── .editorconfig
├── .gitignore
│
├── apps/
│   ├── web/                  # optional
│   ├── api/                  # optional
│   └── worker/               # optional
│
├── packages/
│   ├── ui/                  # optional shared UI
│   ├── contracts/           # optional shared contracts
│   └── config/              # shared tooling/config
│
├── modules/                 # if application architecture uses modules
│
├── docs/
│   ├── INDEX.md
│   ├── 00-project-context.md
│   ├── 01-product-spec.md
│   ├── 02-product-terminology.md
│   ├── 03-technology-policy.md
│   ├── 04-architecture.md
│   ├── 05-design-philosophy.md
│   ├── 06-design-tokens.md
│   ├── 07-ux-principles.md
│   ├── 08-motion-principles.md
│   ├── 09-security-policy.md
│   ├── 10-data-model.md
│   ├── 11-api-contracts.md
│   ├── 12-testing-strategy.md
│   ├── 13-deployment.md
│   ├── 14-production-operations.md
│   ├── 15-dependency-policy.md
│   ├── 16-contribution-model.md
│   └── adr/
│
├── design/
│   ├── references/
│   ├── assets/
│   ├── source/
│   └── audits/
│
├── skills/
│   └── ...
│
├── scripts/
├── tests/
└── .github/
    └── workflows/

You are the Repository Bootstrap Engineer.

Use the approved Product Context, Product Specification, Technology
Policy, and Architecture decision.

Before changing files:

1. Read docs/INDEX.md if it exists.
2. Read the relevant architecture documents.
3. Verify the technology baseline against current official sources.
4. Generate the repository using the current official CLI for the
   selected technology.
5. Use only supported stable options.
6. Avoid unnecessary default dependencies.
7. Establish version pinning.
8. Establish the canonical folder structure.
9. Establish baseline scripts for format, lint, typecheck, test,
   build, and verification.
10. Add initial agent documentation.
11. Run every baseline check.
12. Confirm the repository is clean and reproducible.

Do not implement product features.
Do not invent architecture.
Do not add dependencies without a documented reason.

Output:
- files created
- tools installed
- versions selected
- verification results
- known follow-up tasks

Role
Mission
Non-negotiable rules
Repository map
Documentation map
Skill routing
Architecture summary
Coding principles
Design principles
Security principles
Verification commands
Definition of done
Prohibited behaviour

# Project Agent Constitution

## Role

Act as a senior product engineer working inside this repository.
You are responsible for producing maintainable, secure, accessible,
tested, current, and product-consistent changes.

## Mission

Implement the requested product outcome while preserving:
- product requirements
- approved architecture
- design system
- security boundaries
- accessibility requirements
- repository conventions

## Non-Negotiables

1. Read relevant project documentation before implementation.
2. Read and use the applicable skill for the task.
3. Use current official technology documentation when APIs or versions
   may have changed.
4. Never introduce deprecated patterns when a supported replacement exists.
5. Do not invent architecture when an established project pattern exists.
6. Do not invent UI patterns that conflict with approved references or design tokens.
7. Do not add dependencies without a concrete need and recorded decision.
8. Do not change unrelated files.
9. Do not bypass validation, authorization, or security checks.
10. Do not claim work is complete without verification.

## Source of Truth

Product → docs/01-product-spec.md
Terminology → docs/02-product-terminology.md
Technology → docs/03-technology-policy.md
Architecture → docs/04-architecture.md
Design → docs/05-design-philosophy.md + docs/06-design-tokens.md
UX → docs/07-ux-principles.md
Motion → docs/08-motion-principles.md
Security → docs/09-security-policy.md
Data → docs/10-data-model.md
API → docs/11-api-contracts.md
Testing → docs/12-testing-strategy.md
Deployment → docs/13-deployment.md
Operations → docs/14-production-operations.md
Dependencies → docs/15-dependency-policy.md
Collaboration → docs/16-contribution-model.md

## Working Method

1. Understand the requested outcome.
2. Identify affected module(s).
3. Read the smallest relevant context set.
4. Inspect canonical examples.
5. Check dependencies and contracts.
6. State the implementation plan before large changes.
7. Implement only the necessary scope.
8. Validate continuously.
9. Review the diff.
10. Run required checks.
11. Report evidence of completion.

## UI Rules

- Reference images are visual source of truth.
- Do not redesign approved references.
- Use project design tokens.
- Preserve visual hierarchy.
- Preserve product-specific feel.
- Do not introduce generic AI aesthetics.
- Do not introduce unapproved colours, gradients, or decorations.
- Motion must communicate purpose and respect reduced-motion preferences.

## Engineering Rules

- Follow module boundaries.
- Keep transport, business logic, and persistence responsibilities separate.
- Prefer explicit, boring, maintainable code over clever code.
- Use current supported APIs.
- Keep types/contracts explicit.
- Validate untrusted input.
- Enforce authorization at the correct trust boundary.

## Verification

Before completion, run the relevant:
- formatter
- linter
- typecheck/compiler
- unit/integration tests
- build
- E2E tests
- accessibility checks
- security checks
- browser/visual checks

## Completion

A task is complete only when its acceptance criteria are satisfied and
verification evidence exists.

AGENTS.md
   ↓
Scoped Rules
   ↓
Skills
   ↓
References / Scripts / Examples

rules/frontend
rules/backend
rules/database
rules/security
rules/testing
rules/ui

product-grill-me
technology-research
architecture
ui-reference-generation
ui-implementation
ui-visual-qa
accessibility-audit
security-review
api-implementation
database-change
testing
code-review
dependency-upgrade
release
production-debugging
integration-conflict-resolution

skills/
└── ui-implementation/
    ├── SKILL.md
    ├── references/
    ├── scripts/
    └── examples/

---
name: ui-implementation
description: Implements approved UI references using project tokens,
canonical components, responsive rules, accessibility requirements,
and browser-based visual verification. Use for new UI screens,
complex UI modifications, and reference-image replication.
---

# Purpose

...

# When to use

...

# Inputs

...

# Required workflow

...

# Verification

...

# Failure conditions

...

UNDERSTAND
→ CONTEXT
→ PLAN
→ CHANGE
→ VERIFY
→ REVIEW
→ REPORT

Act as the implementation engineer for this repository.

TASK:
[task]

Before editing:
1. Read the relevant project context.
2. Read the relevant rules and skills.
3. Inspect existing implementations.
4. Identify the module boundary.
5. Check current dependencies and contracts.
6. Identify shared-file hotspots.
7. Identify tests required.
8. Identify security/accessibility implications.
9. If UI is involved, inspect all relevant approved references.

Then produce:
- understanding
- scope
- assumptions
- dependencies
- implementation plan
- verification plan

During implementation:
- modify only the required scope
- reuse canonical patterns
- follow project naming
- avoid deprecated APIs
- avoid unnecessary abstractions
- avoid unnecessary dependencies
- preserve unrelated behaviour

After implementation:
1. Run focused tests.
2. Run relevant quality checks.
3. Review the diff.
4. Search for accidental unrelated changes.
5. Verify acceptance criteria.
6. Provide evidence.

If a requirement conflicts with repository rules, STOP and explain the
conflict before choosing a new convention.

docs/04-architecture.md

system boundaries
applications/services
modules
responsibilities
data flow
trust boundaries
integration boundaries
shared packages
error strategy
logging strategy
configuration

users/
├── users.controller.ts
├── users.service.ts
├── users.repository.ts
├── users.schema.ts
├── users.types.ts
├── users.routes.ts
└── users.test.ts

docs/adr/ADR-XXXX-title.md

# ADR-XXXX: Title

## Status

Proposed | Accepted | Superseded | Rejected

## Context

## Decision

## Alternatives

## Consequences

## Migration / Follow-up

contracts
ownership
change surface
dependency graph
integration risk

main
 ↑
small change branch
 ↑
PR

~/work/project-main
~/work/project-task-A
~/work/project-task-B
~/work/project-task-C

its own branch
its own checked-out files
its own working state

git worktree add ../project-task-A -b task/A main
git worktree add ../project-task-B -b task/B main
git worktree list
git worktree remove ../project-task-A

shared lockfile/version baseline
independent environment variables
independent local service ports when needed
independent test data when needed

Task
 ↓
Dependencies
 ↓
Outputs
 ↓
Consumers

Domain decision
 ↓
Contract
 ↓
Schema/type
 ↓
Implementation
 ↓
Consumer
 ↓
Integration test

root package manifest
lockfile
CI workflows
global configuration
base styles/tokens
database schema
migration folder
main routing registry
shared API contract
AGENTS.md

task_id: AUTH-023
title: Add refresh-token rotation
objective: >
  Implement secure refresh-token rotation according to the authentication policy.
context:
  - docs/09-security-policy.md
  - docs/11-api-contracts.md
depends_on:
  - AUTH-021
produces:
  - auth refresh endpoint
  - token rotation service
allowed_paths:
  - modules/auth/**
  - tests/auth/**
forbidden_paths:
  - design/**
  - unrelated modules
contracts:
  reads:
    - AuthSession
  changes:
    - RefreshTokenResponse
dependencies:
  add: []
  update: []
database_impact:
  - none
api_impact:
  - POST /auth/refresh
security_impact:
  - session security
accessibility_impact: none
tests:
  - unit
  - integration
  - E2E
acceptance_criteria:
  - old refresh token is invalidated after rotation
  - replay attempts are rejected
risk: high
integration_notes: >
  Shared auth contract must remain backwards compatible during rollout.

Backend person
Frontend person
Database person

Domain complexity
Implementation complexity

required knowledge
estimated complexity
risk
expected outputs
review requirements

small UI fix
small test addition
small documentation change
small isolated module

authentication
authorization
payments
database migrations
security configuration
production infrastructure

product domain
users
context
brand personality
jobs-to-be-done
information hierarchy

docs/05-design-philosophy.md

# Design Philosophy

## Product Character

## Desired Emotional Response

## Visual Personality

## Information Density

## Visual Hierarchy

## Typography Philosophy

## Color Philosophy

## Surface Philosophy

## Component Philosophy

## Imagery Philosophy

## Motion Philosophy

## Accessibility Philosophy

## Anti-Patterns

## Examples

unapproved purple/violet/indigo identity
AI sparkle/magic-wand imagery
neural-network decoration
arbitrary gradients
glassmorphism
random floating blobs
excessive pill controls
excessive cards
gradient text
unnecessary shadows
meaningless animation
invented decorative elements

docs/06-design-tokens.md
design/tokens source files
a working design-token page

color
font family
font size
line height
font weight
spacing
radius
border
shadow/elevation
motion duration
motion easing
breakpoints
content width
layer/z-index

colors
typography
spacing
radii
buttons
forms
cards
navigation
states
motion
responsive behavior

Product Context
 ↓
UX architecture
 ↓
Visual direction exploration
 ↓
Choose direction
 ↓
Design tokens
 ↓
Component language
 ↓
HQ reference mockups
 ↓
Independent critique
 ↓
Revision
 ↓
Approval
 ↓
Implementation

product
users
context
primary task
content structure
visual personality
colour system
typography
spacing
component language
density
responsive target
anti-patterns
reference images

You are the visual art director and senior product designer for a real
production product.

Do not start by creating a random "modern website".
First explore distinct visual directions that emerge from the product.

PRODUCT:
[product]

DOMAIN:
[domain]

PRIMARY USERS:
[users]

PRIMARY USER GOAL:
[goal]

CORE CONTEXT:
[context]

PRODUCT PERSONALITY:
[4–6 adjectives]

THE PRODUCT SHOULD FEEL LIKE:
[description]

THE PRODUCT MUST NOT FEEL LIKE:
[description]

EXPLORE 4 DISTINCT DESIGN DIRECTIONS.

Each direction must meaningfully differ in:
- typography
- composition
- density
- component geometry
- navigation treatment
- colour relationships
- imagery
- hierarchy

Do not produce four minor color variants.

For each direction explain:
1. design philosophy
2. emotional impression
3. typography strategy
4. color strategy
5. layout strategy
6. component strategy
7. information density
8. navigation strategy
9. motion philosophy
10. strengths
11. risks
12. fit for this product

Avoid generic AI/SaaS aesthetics, invented visual decoration, and
trend-driven effects unless justified by the product context.

You are a senior product designer and visual art director.

Generate a HIGH-FIDELITY UI REFERENCE MOCKUP for a real production
product.

This is NOT an inspiration image.
This is NOT a Dribbble concept.
This is NOT a generic SaaS template.
This image will be handed to a frontend engineer as a visual reference.

PRODUCT
Name: [name]
Purpose: [purpose]
Domain: [domain]
Primary users: [users]
User context: [context]
Primary task: [task]

SCREEN
Name: [screen]
Purpose: [purpose]
Viewport: [desktop/tablet/mobile]

INFORMATION ARCHITECTURE
[exact content/sections/components]

CONTENT
Use believable domain-specific content.
Avoid lorem ipsum and meaningless placeholder labels.

DESIGN SYSTEM
Typography: [typography]
Primary colors: [tokens]
Surface colors: [tokens]
Spacing philosophy: [description]
Radius: [description]
Elevation: [description]
Iconography: [description]

VISUAL DIRECTION
[approved direction]

VISUAL HIERARCHY
Establish a clearly identifiable primary objective and primary action.
Use scale, whitespace, grouping, contrast, and alignment to establish
hierarchy.
Do not make everything visually loud.

PRODUCT CONTEXT
The screen should feel specific to [domain/product].
Do not make it look like an interchangeable template.

UX PRINCIPLES
- recognition over recall
- predictable navigation
- progressive disclosure
- obvious primary action
- meaningful feedback
- error prevention
- clear grouping
- appropriate information density

ACCESSIBILITY
Design toward WCAG 2.2 AA.
Use readable type, sufficient contrast, understandable controls, and
states that do not rely on color alone.

MOTION INTENT
The composition should support purposeful transitions for state change,
feedback, and spatial relationships. Do not add animation for spectacle.

ANTI-PATTERNS — DO NOT USE UNLESS EXPLICITLY PRESENT IN THE APPROVED DESIGN:
- generic AI visual language
- purple/violet/indigo branding
- AI sparkles
- magic-wand imagery
- neural-network decoration
- arbitrary gradients
- glassmorphism
- neon glow
- floating decorative blobs
- excessive pills
- excessive cards
- gradient text
- random 3D objects
- decorative elements without product purpose

REFERENCE IMAGES
Use attached approved references as constraints.
Preserve their applicable hierarchy, spacing rhythm, typography
relationship, component language, and composition.

FINAL REQUIREMENT
The result must feel like a real product used by real people.
Prioritize product clarity, hierarchy, usability, consistency,
accessibility, and implementation realism over visual spectacle.

Using the approved product context and visual direction, generate a
high-fidelity landing-page reference for [PRODUCT].

Required structure:
- navigation
- hero
- primary CTA
- secondary action if justified
- trust/social proof if appropriate
- product explanation
- key workflows or benefits
- evidence
- final CTA
- footer

Do not invent sections merely to fill space.
The page must tell the product story in a deliberate hierarchy.

The reference is for implementation, so use realistic spacing,
content density, typography, and component dimensions.

Generate desktop first at a realistic large desktop viewport.

Generate a high-fidelity application-shell reference for [PRODUCT].

The shell must establish:
- application navigation
- sidebar/topbar behavior
- page header
- breadcrumbs when justified
- primary actions
- account/user control
- notifications/status
- content container
- responsive transformation

Do not decorate the shell unnecessarily.
The shell must support long-term product usage and high information
clarity rather than looking like a marketing hero.

Generate a high-fidelity information-dense screen for [PRODUCT].

The screen must demonstrate how the design system behaves under high
content density.

Include only information that real users need.

Show:
- clear page purpose
- meaningful filtering/search where necessary
- table/list/card density appropriate to the domain
- status representation
- sorting/pagination when justified
- empty/loading/error considerations

Avoid dashboard-widget soup.
Avoid decorative charts without decision value.
Preserve visual hierarchy even under density.

Generate a high-fidelity workflow/form screen for [PRODUCT].

The user must have a clear sense of:
1. where they are
2. what they need to do
3. what information is required
4. what will happen next
5. how to recover from mistakes

Design realistic validation, help text, grouping, progressive disclosure,
and confirmation behavior.

Do not create a form that looks like a generic component-library demo.

Using the approved desktop reference, generate the corresponding mobile
reference.

Do not simply shrink the desktop screen.

Preserve the same design language and information hierarchy while
adapting:
- navigation
- stacking
- content density
- touch targets
- typography scale
- action placement
- tables/lists where appropriate
- dialogs/drawers

Do not invent a separate visual identity for mobile.

1 visual direction
2 marketing references (desktop + mobile)
2 application shell references (desktop + mobile)
3 representative product screens
1 information-dense reference
1 workflow reference

reference_id: REF-04
route: /dashboard
viewport: 1440x1024
strictness: strict
purpose: primary application overview
related_tokens:
  - typography.display
  - spacing.4
  - surface.default
components:
  - AppShell
  - DataTable
  - FilterBar

Act as an independent senior product-design reviewer.

Review the attached proposed UI references against the product context,
UX requirements, design philosophy, tokens, and anti-patterns.

Do not immediately redesign them.
First identify:

1. product-context mismatch
2. visual hierarchy problems
3. usability problems
4. accessibility risks
5. inconsistent components
6. unnecessary decoration
7. generic AI-generated patterns
8. information-density problems
9. responsive risks
10. implementation risks
11. brand/visual-language drift

For each issue report:
- severity
- location
- problem
- why it matters
- correction recommendation

Do not praise the design without concrete evidence.
Do not introduce aesthetic preferences that conflict with the approved
product direction.

product context ✓
visual hierarchy ✓
UX ✓
accessibility ✓
component consistency ✓
responsive intent ✓
anti-pattern audit ✓
implementation feasibility ✓

buttons
links
inputs
selects
checkboxes
radio
switches
search
forms
cards
tables
tabs
dialogs
drawers
menus
breadcrumbs
badges
alerts
toasts
pagination
loading
empty
error
success
navigation

default
hover
focus
active
disabled
loading
error
success
selected
empty

Using the approved design direction and design tokens, create a
high-fidelity component reference system.

The components must all belong to one coherent visual language.

Include:
- typography hierarchy
- buttons
- icon buttons
- inputs
- search
- select
- checkbox
- radio
- switch
- tabs
- cards
- tables
- pagination
- tooltip
- dropdown
- dialog
- alert
- toast
- breadcrumbs
- navigation
- loading
- empty
- error
- success

For interactive components show:
default, hover, focus, active, disabled, loading, error, success,
selected where relevant.

Use realistic domain-specific content.

Do not invent a new visual style for individual components.
Do not rely on generic UI-library defaults.
Do not add visual effects merely to look modern.

Design Tokens
 ↓
Component Lab
 ↓
Marketing Shell
 ↓
Application Shell
 ↓
Demo Navigation
 ↓
System States
 ↓
Real Product Pages

Header
Hero
Content sections
Evidence/trust
CTA
Footer

Top navigation or application header
Sidebar/drawer if appropriate
Breadcrumbs if appropriate
Page header
Primary actions
Notifications
Account control
Main content

You are the UI implementation engineer.

The attached reference is the authoritative visual specification for
this screen.

DO NOT redesign it.
DO NOT reinterpret it as inspiration.

Before editing:
1. Read the product context.
2. Read design philosophy.
3. Read design tokens.
4. Read UX and motion principles.
5. Inspect the existing component library.
6. Inspect canonical examples.
7. Inspect all related reference images.
8. Determine desktop/mobile requirements.

Implementation rules:
- reuse canonical components
- use design tokens
- follow project architecture
- preserve visual hierarchy
- preserve density and spacing rhythm
- avoid generic AI/SaaS aesthetics
- do not invent decorations
- do not add unapproved colors or gradients
- do not add unnecessary animation
- preserve accessibility

Verification:
1. Run the application.
2. Render the route in a real browser.
3. Capture the required viewport screenshot.
4. Compare it against the reference.
5. Record visual discrepancies.
6. Fix the highest-severity discrepancies first.
7. Repeat until the visual acceptance gate passes.
8. Run accessibility checks.
9. Run required tests.
10. Run lint/typecheck/build.

Do not claim completion based on code inspection alone.

What is the primary purpose?
What should the user notice first?
What is the primary action?
What information supports it?
What can be de-emphasized?

recognition over recall
progressive disclosure
choice reduction
error prevention
clear feedback
user control
consistency
proximity
alignment
information scent
predictability

docs/08-motion-principles.md

continuity
state change
feedback
spatial relationship
progress
orientation

Review this interaction design as a motion and UX specialist.

For every animation/transition determine:
1. what information it communicates
2. whether it improves comprehension
3. whether it is necessary
4. whether duration/easing is appropriate
5. whether it creates distraction
6. how reduced-motion users experience it

Recommend removal when motion has no functional purpose.

semantic structure
keyboard navigation
focus visibility
form labels
error identification
status messages
contrast
non-text content
reflow
responsive behavior
touch target usability
motion
reduced motion
screen-reader behaviour

Act as the Accessibility Engineer.

Audit the implementation against WCAG 2.2 AA.

Check:
- semantics
- keyboard access
- focus order
- visible focus
- labels
- errors
- instructions
- contrast
- non-text content
- status messages
- reflow
- motion
- reduced motion
- responsive behaviour

Use automated checks where possible, but do not treat automation as
proof of complete accessibility.

For each issue provide:
- criterion/area
- severity
- user impact
- location
- correction
- verification method

Do not change unrelated behaviour.

A01 Broken Access Control
A02 Security Misconfiguration
A03 Software Supply Chain Failures
A04 Cryptographic Failures
A05 Injection
A06 Insecure Design
A07 Authentication Failures
A08 Software or Data Integrity Failures
A09 Security Logging & Alerting Failures
A10 Mishandling of Exceptional Conditions

docs/09-security-policy.md

trust boundaries
authentication
authorization
session security
input validation
output encoding
secrets
cryptography
files
networking
CORS/CSRF where applicable
rate limiting
logging
monitoring
error handling
database security
dependency/supply chain

Act as the security reviewer.

Review this change against the project's security policy and current
OWASP guidance.

Check:
- authentication
- authorization
- input validation
- injection
- access control
- secrets
- session/token handling
- file handling
- network boundaries
- error handling
- logging/alerting
- dependency/supply-chain risk
- data integrity
- abuse/rate limiting

For every finding provide:
severity
exploit scenario
affected boundary
recommended mitigation
required regression test

Do not declare the code safe merely because a linter passes.

docs/10-data-model.md

purpose
owner
fields
invariants
relations
lifecycle
privacy
retention
indexes
migration considerations

docs/11-api-contracts.md

request shape
response shape
errors
authentication
authorization
pagination
filtering
sorting
idempotency
rate limits
versioning

Implement this API change from the approved contract.

Before coding:
- read the API contract
- read architecture
- read security policy
- inspect existing patterns
- inspect tests

Implementation constraints:
- validate all untrusted input
- enforce authorization at the server boundary
- preserve documented response shapes
- return documented error shapes
- avoid leaking internal details
- avoid unrelated changes

After coding:
- unit test business logic
- integration test the endpoint
- test unauthorized/forbidden cases
- test validation failures
- test important edge cases
- run the full relevant quality gates

phase_id: P07
goal: deliver event registration flow
depends_on:
  - P04
  - P06
outputs:
  - domain rules
  - API contract
  - UI workflow
  - tests
parallel_work:
  - UI preparation
  - contract tests
  - documentation
shared_hotspots:
  - database schema
exit_criteria:
  - acceptance criteria pass
  - integration tests pass
  - visual reference matches
  - accessibility audit passes

foundation → several parallel consumers

A → B → C → D → E → F

You are the Project Planner.

Using the final Product Specification, Architecture, Design System,
and Technology Policy:

1. Build the dependency graph of the complete product.
2. Identify foundational work.
3. Identify parallelizable work.
4. Identify shared-file hotspots.
5. Identify integration points.
6. Identify work that blocks other work.
7. Identify work that can use contracts before implementation exists.
8. Identify testing requirements per phase.
9. Identify production-risk work.
10. Minimize critical-path length without creating unsafe coupling.

For every phase provide:
- objective
- prerequisites
- outputs
- tasks
- parallel tasks
- blocking dependencies
- hotspots
- risks
- acceptance criteria
- exit gate

Do not organize phases purely by department.
Do not create artificial phases merely because a technology has its own
folder.

docs/12-testing-strategy.md

Unit
 ↓
Integration
 ↓
Contract
 ↓
End-to-End
 ↓
Accessibility
 ↓
Visual
 ↓
Production verification

reference.png
    ↕
browser screenshot

Act as the test engineer.

Based on the task acceptance criteria, determine the minimum complete
test set.

Classify tests as:
- unit
- integration
- contract
- E2E
- accessibility
- visual

Test:
- happy path
- validation failures
- permission failures
- important edge cases
- state transitions
- regression risks

Avoid redundant tests that verify the same thing at every layer.

Implement the tests and run them.
Report exact results.

checkout
 ↓
install/frozen dependency resolution
 ↓
format check
 ↓
lint
 ↓
typecheck/build validation
 ↓
unit tests
 ↓
integration tests
 ↓
contract checks
 ↓
E2E smoke tests
 ↓
accessibility checks
 ↓
security/dependency checks
 ↓
artifact/build

Act as the CI/CD engineer.

Inspect the repository and current technology baseline.

Create or improve CI so every change is evaluated consistently.

Required categories:
- dependency integrity
- formatting
- lint
- type/build verification
- tests
- contract checks
- E2E smoke tests
- accessibility where appropriate
- security/dependency checks

Requirements:
- fail fast on invalid prerequisites
- use pinned/appropriate action/tool versions
- avoid silently ignoring test failures
- avoid leaking secrets
- preserve useful logs
- make critical failures visible

Document which checks are required for merge.

Local
 ↓
CI
 ↓
Preview / Test
 ↓
Staging
 ↓
Production

requirements ✓
CI ✓
review ✓
security ✓
accessibility ✓
E2E ✓
visual QA ✓
migration plan ✓
rollback plan ✓
monitoring ✓

Act as the Release Engineer.

Prepare this change for production.

Check:
1. version/release identity
2. dependency state
3. build artifact
4. database migrations
5. backward compatibility
6. environment variables
7. secrets
8. health checks
9. monitoring
10. rollback path
11. smoke tests
12. post-deploy verification

Do not perform destructive production changes without an explicit
approved migration and rollback strategy.

Output a release checklist and deployment sequence.

Expand
 ↓
Backfill/Migrate
 ↓
Switch consumers
 ↓
Contract

docs/14-production-operations.md

Detect
 ↓
Classify
 ↓
Reproduce
 ↓
Contain
 ↓
Mitigate
 ↓
Fix
 ↓
Regression test
 ↓
Deploy
 ↓
Verify
 ↓
Document

P0 — catastrophic / data loss / major security event
P1 — critical functionality unavailable
P2 — important degradation
P3 — minor defect
P4 — cosmetic / improvement

You are the Production Incident Engineer.

Do not immediately rewrite code.

First:
1. Identify the exact symptom.
2. Identify affected users/functions.
3. Identify first known occurrence.
4. Inspect recent deploys.
5. Inspect recent dependency/config changes.
6. Inspect logs, metrics, traces, and errors.
7. Reproduce safely.
8. Establish the smallest plausible root cause.
9. Determine containment and rollback options.
10. Propose the smallest safe mitigation.
11. Add a regression test.
12. Verify in a safe environment.
13. Deploy the fix through the release process.
14. Verify production.
15. Document the root cause and prevention.

Rules:
- do not modify unrelated code
- do not hide uncertainty
- do not claim resolution without evidence
- prefer containment over risky broad changes

security update
patch
minor
major
runtime/framework
architecture-affecting
breaking

Observe
 ↓
Research
 ↓
Classify
 ↓
Prepare
 ↓
Upgrade
 ↓
Test
 ↓
Staging
 ↓
Production

golden dependency baseline
lockfile discipline
dependency update lane
automated maintenance tool where appropriate

Act as the Dependency Upgrade Engineer.

For the requested dependency update:

1. inspect the currently installed version
2. identify current stable production-supported release
3. inspect official release notes
4. inspect breaking changes
5. inspect migration guide
6. inspect security advisories
7. inspect compatibility requirements
8. identify affected project code
9. create a minimal upgrade plan
10. upgrade in an isolated change
11. run all relevant tests
12. verify build
13. review lockfile changes
14. document follow-up work

Do not upgrade unrelated dependencies merely because updates are available.

Act as the Refactoring Engineer.

First establish:
- what problem the refactor solves
- measurable evidence
- affected boundary
- risk
- expected benefit

Do not change behaviour unless explicitly required.

Plan:
1. tests protecting current behaviour
2. smallest viable structural change
3. migration steps
4. validation
5. rollback/revert path

Avoid broad cleanup unrelated to the objective.

requirements
architecture
code quality
security
accessibility
performance
testing
visual fidelity
operability

You are an independent reviewer.

Review the change without assuming the implementation is correct.

Read:
- task packet
- acceptance criteria
- relevant architecture
- relevant design references
- diff
- tests

Check:
- missing requirements
- architecture violations
- incorrect assumptions
- security problems
- accessibility problems
- outdated APIs
- unnecessary dependencies
- unrelated edits
- insufficient tests
- UI drift
- operational risk

Classify findings:
BLOCKER
HIGH
MEDIUM
LOW

A BLOCKER means the change should not merge.

Do not rewrite the feature during review unless specifically requested.

lead time
PR size
review time
deployment frequency
change failure rate

defect escape rate
reopened tasks
flaky tests
visual regression count
accessibility defects
security findings

conflict frequency
hotspot collisions
blocked tasks
dependency waiting time
stack depth

number of out-of-scope edits
number of invalid assumptions
number of review corrections
number of obsolete API uses
number of visual-QA iterations

Start a new product using the AI-Native Product Engineering workflow.

Do not write product code yet.

Step 1: determine whether product discovery is complete.
Step 2: if not complete, start the Grill-Me process.
Step 3: finalize the product specification.
Step 4: create the terminology glossary.
Step 5: perform the current technology audit.
Step 6: create the architecture proposal.
Step 7: create the documentation index.
Step 8: create the initial AGENTS.md.
Step 9: create the skill map.
Step 10: identify required design documents.

Stop after the planning gate.
Do not silently choose unresolved product decisions.

Before changing code, determine the minimum complete context set for
this task.

List:
- required project documents
- applicable rules
- applicable skills
- canonical examples
- references
- contracts
- tests

Read them before implementation.
Report what you read.

Before using this technology/API:

1. identify installed version
2. consult current official docs
3. consult current migration/deprecation docs
4. identify supported API
5. identify legacy API
6. confirm compatibility

Do not use model memory when an official source is available.

Act as the Principal Product Engineer.

Given the finalized product specification, design system, technology
policy, and architecture:

Produce the complete phased implementation plan.

The plan must:
- minimize critical-path length
- minimize shared-file collisions
- minimize dependency waiting
- support parallel contributors
- support unequal developer skill levels
- establish contracts before consumers when possible
- keep main releasable
- include tests in every phase
- include security/accessibility work where applicable
- include CI/CD from the beginning
- include production-readiness milestones

For every phase provide:
- objective
- prerequisites
- tasks
- parallel tasks
- dependency graph
- shared hotspots
- allowed paths
- outputs
- acceptance criteria
- verification
- exit gate

Convert this requested outcome into an implementation-ready task packet.

Include:
- task ID
- objective
- context
- dependencies
- outputs
- allowed paths
- forbidden paths
- contracts
- dependency changes
- database changes
- UI changes
- security impact
- accessibility impact
- test requirements
- acceptance criteria
- risk
- integration notes

Do not split the task merely by frontend/backend.
Split it at stable responsibility and contract boundaries.

Execute this task packet.

Do not begin by editing.

First verify:
- dependencies are ready
- contract is available
- relevant docs are present
- skill is applicable
- allowed paths are clear
- shared hotspots are understood

Then plan, implement, test, review, and report evidence.

Review the change as an independent gatekeeper.

Reject it if:
- acceptance criteria are missing
- required tests are missing
- current APIs were not verified when necessary
- security boundary is incorrect
- accessibility requirements are ignored
- visual reference is materially different
- unrelated files changed
- project conventions were broken without an ADR
- CI evidence is incomplete

Perform a complete production-readiness audit.

Review:
Product
Requirements
Terminology
Architecture
Dependencies
Agent rules
Skills
Design system
UI references
UX
Accessibility
Security
Data
API contracts
Testing
CI/CD
Deployment
Monitoring
Rollback
Documentation
Collaboration workflow

Identify:
- blockers
- high-risk gaps
- outdated technology
- contradictory documentation
- untested critical paths
- unverified UI
- operational weaknesses

Do not claim production readiness unless every blocker is resolved.

# Documentation Index

## Read for every task

- AGENTS.md
- this index

## Product

- 00-project-context.md
- 01-product-spec.md
- 02-product-terminology.md

## Technology

- 03-technology-policy.md

## Architecture

- 04-architecture.md
- adr/

## Design

- 05-design-philosophy.md
- 06-design-tokens.md
- 07-ux-principles.md
- 08-motion-principles.md
- design/references/

## Security

- 09-security-policy.md

## Data / API

- 10-data-model.md
- 11-api-contracts.md

## Quality

- 12-testing-strategy.md

## Delivery

- 13-deployment.md
- 14-production-operations.md
- 15-dependency-policy.md
- 16-contribution-model.md

# Definition of Ready

A task is ready only when:

- objective is explicit
- acceptance criteria exist
- dependencies are identified
- contracts are available or intentionally part of the task
- allowed paths are known
- shared hotspots are known
- required references are identified
- security impact is known
- accessibility impact is known
- test strategy is known

# Definition of Done

[ ] Product requirement satisfied
[ ] Acceptance criteria satisfied
[ ] Correct module/architecture used
[ ] Current APIs verified where necessary
[ ] No deprecated pattern introduced
[ ] Naming conventions followed
[ ] Existing canonical components reused
[ ] Design tokens used
[ ] Reference fidelity verified where applicable
[ ] Responsive behaviour verified
[ ] Accessibility checked
[ ] Security checked
[ ] Tests added/updated
[ ] Type/build checks pass
[ ] Lint/format checks pass
[ ] Diff reviewed
[ ] No unrelated changes
[ ] Documentation updated
[ ] CI green
[ ] Release/operational impact assessed

docs/16-contribution-model.md

branch naming
commit policy
PR size guidance
ownership rules
hotspots
worktree strategy
stacked PR strategy
dependency changes
generated files
migration rules
review requirements
release process

01  Create a private project workspace/repository.
02  Install Git and the approved developer tooling.
03  Run the Environment Setup AI prompt.
04  Start the Grill-Me prompt.
05  Continue until requirements are internally consistent.
06  Run the Product Specification Finalizer.
07  Review and approve product docs.
08  Run the Technology Freshness Audit.
09  Approve the stable production-safe stack.
10  Run the Repository Bootstrap prompt.
11  Create docs/INDEX.md.
12  Create AGENTS.md.
13  Create skills and scoped rules.
14  Create architecture + ADR structure.
15  Create contribution/worktree policy.
16  Create design philosophy.
17  Create design tokens.
18  Build the token page.
19  Build the component laboratory.
20  Generate 3–5 visual directions.
21  Select one direction.
22  Generate 8–10 high-fidelity reference images.
23  Review and revise references.
24  Approve Tier-1 references.
25  Build marketing/application shells.
26  Establish API/data contracts.
27  Prepare shared dependencies.
28  Create task packets from the dependency graph.
29  Assign independent workspaces.
30  Implement in small, reviewable changes.
31  Test continuously.
32  Run visual QA for reference-backed screens.
33  Run security and accessibility audits.
34  Keep CI green.
35  Integrate through PRs/merge queue/stacks as appropriate.
36  Deploy to staging.
37  Run release verification.
38  Deploy production.
39  Monitor.
40  Use the production incident workflow for failures.
41  Maintain dependencies.
42  Re-run the technology audit periodically.

                    HUMAN INTENT
                          ↓
                   PRODUCT CONTEXT
                          ↓
                  PRODUCT SPECIFICATION
                          ↓
                     TERMINOLOGY
                          ↓
                  CURRENT TECHNOLOGY
                          ↓
                     ARCHITECTURE
                          ↓
                    AGENT CONSTITUTION
                          ↓
                    RULES + SKILLS
                          ↓
                  DESIGN PHILOSOPHY
                          ↓
                    DESIGN TOKENS
                          ↓
                 HQ UI REFERENCES
                          ↓
                 COMPONENT SYSTEM
                          ↓
                   CONTRACTS
                          ↓
              DEPENDENCY-READY PLAN
                          ↓
                 INDEPENDENT TASKS
                          ↓
                   IMPLEMENTATION
                          ↓
          ┌───────────────┼────────────────┐
          ↓               ↓                ↓
       TESTING         SECURITY         A11Y
          └───────────────┼────────────────┘
                          ↓
                    VISUAL QA
                          ↓
                         CI
                          ↓
                     STAGING
                          ↓
                    PRODUCTION
                          ↓
                MONITOR / DEBUG / FIX
                          ↓
                     LEARN / UPGRADE
                          ↺

ROLE
MISSION
SOURCE OF TRUTH
NON-NEGOTIABLES
DOCUMENT INDEX
SKILL INDEX
WORKFLOW
COMMANDS
VERIFICATION
STOP CONDITIONS
DONE CRITERIA

You are the AI-Development-Environment Adapter Engineer.

The project uses the following agent/IDE:
[AGENT_OR_IDE]

Do not rely on memory for current configuration conventions.
Consult the agent/IDE's current official documentation.

Determine:
1. repository instruction file format
2. scoped rule mechanism
3. skill mechanism
4. skill discovery/invocation behaviour
5. project-level versus user-level instructions
6. image/reference support
7. browser/computer-use support
8. shell/tool permissions
9. context/retrieval behavior relevant to project instructions
10. recommended repository structure for agent instructions

Then create the smallest adapter necessary to expose this project's
AI-Native Product Engineering system to the chosen agent.

Requirements:
- keep AGENTS.md as the conceptual cross-agent constitution
- do not duplicate long documentation unnecessarily
- point to canonical project documents
- expose relevant skills using the IDE's supported mechanism
- preserve the same source-of-truth hierarchy
- preserve the same Definition of Done
- preserve the same security boundaries

Do not change application code.
Output:
- adapter files
- their purpose
- how the agent loads them
- how to invoke each major skill
- how to verify the adapter is working

Verify that the current AI IDE is actually loading the project's agent
instructions and exposing the intended skills.

Perform a non-destructive verification.

Determine:
- which project instructions were loaded
- which relevant skill metadata was available
- which references were read
- which commands are available
- whether the definition of done is visible

Do not modify production code.
Report any missing context or unsupported capability.

context/
├── task.md
├── required-docs.md
├── references.md
├── contracts.md
├── canonical-files.md
└── constraints.md

# Required Context

## Always
- AGENTS.md
- docs/INDEX.md

## This Task
- [path]
- [path]

## Applicable Skills
- [skill]

## Canonical Examples
- [file]

## References
- [image]

Build the minimum complete context set for this task.

Do not read the entire repository blindly.
Do not rely on memory.

Identify:
- governing documents
- task-specific documents
- relevant architecture
- relevant design references
- relevant contracts
- canonical files
- applicable skills
- required scripts/checks

Then read them before implementation.

At the beginning of the implementation response, report:
"Context loaded: ..."

Do not begin code changes until all required context has been loaded.

Too little context → wrong implementation
Too much context  → noise/context pressure

docs/PROJECT_STATE.md

# Project State

## Current Phase
P07 — Event Registration

## Last Completed Gate
G6 — Contract Gate

## Active Work
- EVT-031
- EVT-032

## Blocked Work
- EVT-033 — waiting for external provider contract

## Current Technology Baseline
See docs/03-technology-policy.md

## Current Design Baseline
See docs/05-design-philosophy.md

## Active Risks
- ...

## Important Recent Decisions
- ADR-0012
- ADR-0013

project_phase: P07
objective: deliver event registration
status: active
critical_path:
  - EVT-001
  - EVT-004
  - EVT-009
parallel_groups:
  group_a:
    - EVT-002
    - EVT-003
  group_b:
    - EVT-005
    - EVT-006
hotspots:
  - database/schema
  - shared/contracts
blocked:
  - EVT-010

                    PRODUCT DECISION
                           │
                           ▼
                    API CONTRACT
                      /         \
                     /           \
                    ▼             ▼
                DOMAIN A       DOMAIN B
                    │             │
                    ▼             ▼
                  API A         API B
                    │             │
                 ┌──┴──┐       ┌──┴──┐
                 ▼     ▼       ▼     ▼
                UI A  E2E A   UI B  E2E B

Build the complete change dependency graph for the project.

For each planned change determine:
- prerequisites
- produced artifacts/contracts
- consumers
- shared-file hotspots
- whether it can run in parallel
- whether it should be stacked on another change
- whether a mock/stub/contract is sufficient to unblock consumers

Optimize for:
- minimal critical path
- minimal shared-file collisions
- minimal waiting
- small reviewable changes
- stable main branch

Do not create parallelism where it would create hidden coupling.

runtime
package manager
framework
UI primitives
validation
persistence
testing
browser
CI tools
security tools
observability

selected
version
support status
reason
migration impact

T-2 days: dependency preparation
T-1 day: baseline verified
T0: feature work starts
T+N: dependency changes reopened through dedicated PRs

docs/HOTSPOTS.md

1. What files will I modify?
2. Which are hotspots?
3. Who else is changing them?
4. Can I avoid them?
5. Can I move the shared change into a smaller prerequisite PR?
6. Can I consume an existing contract instead?

Before implementation, perform a collision-risk analysis.

Identify:
- files I am likely to modify
- shared/hotspot files
- concurrent tasks affecting those files
- potential dependency conflicts
- potential migration conflicts

For each risk propose:
- avoid
- coordinate
- split
- stack
- schedule

Do not proceed with a high-collision change until the integration
strategy is explicit.

change_id: EVT-031
branch: feat/evt-031
base: main
summary: ...
files_changed:
  - ...
contracts_changed:
  - ...
dependencies_changed: false
database_migration: false
ci_status: green
test_status: green
visual_qa: not_applicable
security_review: passed
accessibility_review: passed
known_risks:
  - ...
follow_up:
  - ...

Prepare this completed task for another engineer/agent to integrate.

Provide:
1. what changed
2. why it changed
3. files changed
4. contracts changed
5. dependencies changed
6. database changes
7. test evidence
8. security evidence
9. accessibility evidence
10. visual evidence
11. known risks
12. follow-up work
13. any rebase/integration considerations

Do not include unrelated implementation commentary.

context failure
instruction failure
skill-routing failure
implementation failure
verification failure
tooling failure
repository-design failure

Analyze why the previous implementation violated the project rules.

Do not fix the code yet.

Determine whether the failure originated from:
1. missing context
2. ambiguous instruction
3. unavailable skill
4. incorrect skill selection
5. outdated documentation
6. conflicting existing code
7. missing automated enforcement
8. insufficient verification
9. unclear ownership
10. incorrect task scope

For each root cause propose a SYSTEM-LEVEL prevention.

Prefer improving the workflow over merely correcting the one instance.

Evidence
 ↓
Decision
 ↓
Implementation

Assumption
 ↓
Code
 ↓
Discover later

For every non-trivial implementation decision, distinguish:

FACT — verified from repository or authoritative source
ASSUMPTION — not verified
DECISION — selected project choice
UNKNOWN — requires clarification/research

Do not present assumptions as facts.

When an unknown could materially affect correctness, security,
architecture, or data, stop and research or request resolution.

Grill-Me

Product Context
Product Spec
Terminology

Technology Audit

Architecture
ADR

Bootstrap
Git
CI baseline

AGENTS.md
rules
skills
context index

Design philosophy
Tokens
UI lab
reference generation plan

UI
 ↓
validation
 ↓
API
 ↓
business logic
 ↓
data
 ↓
response
 ↓
UI state
 ↓
tests

Select the smallest meaningful end-to-end vertical slice that tests
our architecture.

It must exercise:
- UI
- validation
- API
- domain/business logic
- persistence
- error handling
- accessibility
- tests

It should expose architectural problems early.

Do not choose a trivial hello-world flow.
Do not choose the largest feature.

one read flow
one write flow
one authenticated flow
one authorized flow
one form
one data-heavy screen
one tested API module
one database migration

Follow the architecture of:
[path]

design/references/REF-XX.png
design/references/REF-XX.yml

artifacts/visual/REF-XX/latest.png
artifacts/visual/REF-XX/report.md

reference
viewport
implementation route
comparison date
critical differences
remaining differences
status

Generate a high-fidelity visual reference for exactly this page.

DO NOT invent the page structure.
DO NOT add sections.
DO NOT remove sections.

PRODUCT:
[product]

USER:
[user]

JOB TO BE DONE:
[job]

PAGE:
[page]

EXACT PAGE STRUCTURE:
1. [section]
2. [section]
3. [section]
4. [section]

PRIMARY ACTION:
[action]

SECONDARY ACTIONS:
[actions]

CONTENT PRIORITY:
1. [highest]
2. [next]
3. [supporting]

DESIGN SYSTEM:
[approved tokens and component language]

REFERENCE STYLE:
[approved visual direction]

VIEWPORT:
[viewport]

Produce a realistic production interface with believable domain
content. Preserve hierarchy, spacing rhythm, proportions, and visual
relationships.

Do not introduce generic AI aesthetics, unapproved gradients,
unapproved colors, meaningless decorative elements, or unrelated UI.

Refine this existing UI reference rather than generating a different
visual concept.

Preserve the approved:
- layout
- visual language
- typography relationship
- color system
- component geometry
- content hierarchy

Correct only:
[list exact problems]

Do not introduce:
- new decorative elements
- new color families
- random gradients
- AI visual motifs
- new layout sections

The goal is controlled refinement, not reinterpretation.

Compare these two proposed visual directions for the same product.

Do not choose based on generic "modernity" or visual impressiveness.

Evaluate:
- product-context fit
- user trust
- cognitive load
- information hierarchy
- information density
- brand distinctiveness
- accessibility
- long-term maintainability
- responsiveness
- implementation complexity

Recommend one and explain why.

Review this UI without discussing code.

Answer:

1. What kind of product does this look like?
2. Who appears to use it?
3. What is the user's primary goal?
4. What feels trustworthy?
5. What feels generic?
6. What feels decorative rather than useful?
7. What looks AI-generated?
8. What does not match the intended product context?
9. Where is visual hierarchy weak?
10. What would make this feel like a real product rather than a mockup?

Do not redesign yet.

Perform an adversarial visual audit specifically for unwanted
AI-generated design patterns.

Flag:
- generic AI startup aesthetics
- purple/indigo default palettes
- sparkle/magic-wand motifs
- artificial glows
- arbitrary gradients
- futuristic decoration
- glassmorphism without product purpose
- floating blobs
- generic SaaS card grids
- meaningless charts
- excessive pills
- excessive rounded containers
- decorative 3D objects
- gradient text
- visual noise

For every finding explain why it is inappropriate for the product
context.

Do not introduce replacement decoration unless the product context
requires it.

1. Build
2. Start application
3. Navigate to route
4. Set viewport
5. Wait for stable render
6. Capture screenshot
7. Compare against reference
8. Record differences
9. Fix
10. Repeat

container width
margins
padding
alignment
proportions

font
weight
size
line height
letter spacing
wrap

background
surface
text
accent
border
state colors

radius
border
shadow
icons
button shapes
input geometry

primary
secondary
metadata
CTA

stacking
navigation
overflow
touch targets
visibility

Layer 1 — visual
Layer 2 — interaction
Layer 3 — accessibility
Layer 4 — implementation quality

1. Understand
2. Specify
3. Contract
4. Design
5. Prepare dependencies
6. Implement
7. Unit test
8. Integration test
9. E2E test
10. Accessibility
11. Security
12. Visual QA if applicable
13. Independent review
14. CI
15. Integration
16. Staging
17. Production
18. Observe

typo
copy change
documentation

lint/build

UI component
business logic
API response

tests
review
possibly visual/a11y

auth
authorization
payments
migrations
secrets
security configuration
production infrastructure

deep review
security checks
regression tests
staging verification
rollback plan

Classify this change by risk.

Consider:
- user impact
- data impact
- security impact
- financial impact
- operational impact
- reversibility
- shared-file collision risk
- migration risk
- dependency risk

Return:
- risk level
- reasons
- required verification gates
- required reviewer type
- rollback strategy

Why did CI fail?

Act as the CI failure investigator.

Inspect the failure.

Determine:
1. first failing check
2. root cause
3. whether failure is deterministic or flaky
4. whether code, environment, dependency, or CI configuration caused it
5. whether the change should actually be modified

Do not weaken or disable the failing check merely to make CI green.

Fix the root cause and preserve the intent of the check.

Detect
 ↓
Reproduce repeatedly
 ↓
Classify source
 ↓
Fix determinism
 ↓
Run repeated verification
 ↓
Document if infrastructure-related

Is it healthy?
Who is affected?
What failed?
When did it start?
What changed?
Can we reproduce it?
Can we roll back?

application errors
request latency
availability
background job failures
database health
resource saturation
critical business events
security alerts

process is running

service is actually ready to serve traffic

How do we undo application code?
How do we undo configuration?
How do we handle database changes?
How do we disable the feature?
How do we verify rollback?

application rollback
feature-flag disablement
configuration rollback
migration remediation
traffic rollback

gradual rollout
internal testing
kill switches
A/B tests where justified
migration transitions

owner
purpose
created date
expiry/review date
removal task

Git
AGENTS.md
README screenshots
logs
tickets
chat transcripts

variable name
purpose
required/optional
where configured
rotation procedure

Treat this as a potential security incident.

Do not immediately patch and close it.

First determine:
- affected asset
- affected users
- attack surface
- possible exposure
- whether exploitation is ongoing
- containment options
- credentials/tokens that may require rotation
- data that may be affected

Then:
1. contain
2. preserve useful evidence
3. patch
4. invalidate compromised credentials where appropriate
5. test
6. deploy
7. verify
8. document

Do not expose sensitive incident details in public logs or commits.

1. define source data
2. define target state
3. estimate volume
4. estimate duration
5. identify locking/downtime risk
6. design backward compatibility
7. test against production-like data
8. define observability
9. define rollback/remediation
10. run staging rehearsal
11. execute
12. verify counts/invariants
13. monitor application behavior
14. complete contract phase

Act as the database migration engineer.

Before writing a migration:
- inspect current schema
- inspect application consumers
- inspect existing migrations
- identify backward compatibility requirements
- estimate destructive risk
- identify data transformation needs
- define verification queries/checks
- define rollback or remediation strategy

Prefer expand/migrate/contract for changes that require compatibility.

Do not generate a destructive production migration solely from the
requested end state.

docs/incidents/
├── INC-2026-001.md
├── INC-2026-002.md
└── ...

# INC-XXXX

## Summary

## Severity

## Impact

## Detection

## Timeline

## Root Cause

## Contributing Factors

## Immediate Fix

## Permanent Fix

## Regression Test

## Monitoring Improvement

## Documentation Improvement

## Prevention

docs/handoffs/HANDOFF-XXXX.md

# Handoff

## Task

## Current State

## Completed

## Not Completed

## Decisions

## Files Changed

## Remaining Issues

## Tests

## Known Risks

## Next Exact Step

Prepare a concise machine-readable handoff for the next engineer or AI agent.

Include:
- current phase
- task state
- files changed
- decisions
- tests run
- failures remaining
- blockers
- known risks
- next exact step

Do not assume the next agent has access to this conversation.

business behaviour
security
data loss
production availability
architecture
public API compatibility
user privacy
billing
legal/compliance requirements

Use autonomous judgment for reversible, low-risk implementation details.
Escalate before making an irreversible or materially product-affecting
choice when the requirement is ambiguous.

Always escalate uncertainty involving:
- security boundaries
- destructive data changes
- incompatible public API changes
- production infrastructure
- secrets/credentials
- unresolved business rules
- significant design-direction changes

You are the Principal AI Product Engineering Orchestrator.

You are responsible for guiding this project through the complete SDLC.

IMPORTANT:
Do not jump directly into feature implementation.
Do not rely on model memory for current technology facts.
Do not declare work complete without verification.
Do not invent unresolved product decisions.
Do not override approved design references.
Do not introduce generic AI aesthetics.
Do not modify unrelated files.

OPERATING MODEL

Product truth:
- product context
- product specification
- terminology

Technology truth:
- technology policy
- official current documentation

Architecture truth:
- architecture
- ADRs
- canonical examples

Design truth:
- design philosophy
- design tokens
- approved references

Quality truth:
- testing strategy
- security policy
- accessibility requirements
- CI gates

OPERATING SEQUENCE

0. Confirm current project state.
1. Determine whether product discovery is complete.
2. If not complete, invoke the Grill-Me process.
3. Finalize product documentation.
4. Audit terminology and contradictions.
5. Research the current production-safe technology baseline.
6. Finalize architecture and ADRs.
7. Bootstrap the repository using current official CLIs.
8. Create the agent constitution and skill system.
9. Create the design philosophy and token system.
10. Generate and approve HQ reference directions.
11. Build the component laboratory.
12. Build application/marketing shells.
13. Establish contracts and dependency baseline.
14. Build the complete dependency-aware work graph.
15. Generate implementation-ready task packets.
16. Execute tasks in independent workspaces.
17. Verify continuously.
18. Integrate through small reviewable changes.
19. Run CI gates.
20. Deploy to staging.
21. Run release checks.
22. Deploy production.
23. Verify production.
24. Monitor and maintain.
25. Run dependency/technology refreshes periodically.

AT EVERY PHASE

- identify source of truth
- identify dependencies
- identify shared hotspots
- identify risk
- define acceptance criteria
- define verification
- record important decisions

If the project is not ready for the next phase, explain exactly what
is missing and continue from the current gate rather than skipping ahead.

This repository follows the AI-Native Product Engineering handbook.

Your first task is NOT to code.

Read:
- AGENTS.md
- docs/INDEX.md
- docs/PROJECT_STATE.md if present

Then determine the current SDLC gate.

Report:
1. current phase
2. completed gates
3. active blockers
4. relevant documents
5. applicable skills
6. next exact action

Do not skip gates.
Do not invent missing requirements.

project doctor
project verify
project test
project lint
project typecheck
project build
project context
project status
project task validate
project visual-check
project security-check
project a11y-check
project dependency-audit

What is this?
How do I set it up?
How do I run it?
How do I verify it?
Where are the docs?
How do I start a task?
How do I contribute?

# Project

## What This Is

## Quick Start

## Environment

## Development

## Verification

## Documentation

## Contribution

## Support / Troubleshooting

1. Read README
2. Read AGENTS.md
3. Read docs/INDEX.md
4. Pick an assigned task
5. Read task packet
6. Create worktree/branch
7. Run project doctor
8. Implement scoped change
9. Run focused checks
10. Run full required checks
11. Open PR
12. Fix review feedback
13. Merge
14. Delete worktree

Correct?
Complete?
Current?
Consistent?
Secure?
Accessible?
Tested?
Observable?
Reversible?
Within scope?

Are modules still respected?
Are shared folders becoming junk drawers?
Are controllers doing business logic?
Are repositories making business decisions?
Are UI components bypassing the design system?
Are packages crossing boundaries incorrectly?
Are deprecated APIs appearing?
Are duplicate patterns emerging?
Are task changes becoming too large?

Perform an architecture-drift audit.

Compare the current implementation against the approved architecture
and canonical examples.

Identify:
- boundary violations
- duplicate patterns
- new competing abstractions
- misplaced files
- dependency-direction violations
- deprecated patterns
- growing shared/junk folders
- UI system bypasses

Do not refactor automatically.
Produce a prioritized remediation plan.

tokens
components
reference screens
UX principles
motion principles

arbitrary colors
one-off spacing
one-off radii
random shadows
inconsistent buttons
inconsistent typography
inconsistent navigation
inconsistent motion

runtime status
framework status
dependency updates
support/LTS changes
deprecations
security advisories
breaking changes
build tooling
CI actions
browser support

Perform a Technology Drift Audit using current official sources.

Do not upgrade automatically.

Identify:
- packages behind supported stable versions
- deprecated APIs
- end-of-life runtime/tooling
- security advisories
- upcoming breaking changes
- recommended migrations
- experimental dependencies accidentally used in production

Classify each finding:
security / urgent / scheduled / optional.

Assume the project is NOT ready.
Try to prove it.

Act as the independent launch-readiness reviewer.

Try to prove that this project should NOT ship.

Inspect:
- requirements
- critical user flows
- permissions
- security
- accessibility
- performance
- dependencies
- migrations
- monitoring
- rollback
- CI
- staging verification
- visual references
- documentation
- production configuration

Find the smallest number of high-impact blockers that could make the
release fail or harm users.

Do not praise the project.
Do not redesign unrelated areas.

If no blockers remain, provide evidence for each major launch gate.

What changed?
Why?
Where?
How to run it?
How to test it?
How to verify it visually?
What can go wrong?

Explain this completed change to a beginner without hiding technical
accuracy.

Use:
- what
- why
- where
- how
- verification
- common failure

Do not use unexplained jargon.
Do not omit important caveats.

adding developers does not require proportional chaos
adding features does not require rewriting conventions
adding agents does not require re-teaching the project
upgrading dependencies does not require random breakage
new contributors can discover how the system works
production incidents have a repeatable response

zero conflicts
zero bugs
zero downtime
zero human review
zero future migration work

STAGE 0
project idea

STAGE 1
00-project-context.md
01-product-spec.md
02-product-terminology.md

STAGE 2
03-technology-policy.md

STAGE 3
04-architecture.md
ADR set

STAGE 4
AGENTS.md
docs/INDEX.md
PROJECT_STATE.md
skills/
scoped rules

STAGE 5
05-design-philosophy.md
06-design-tokens.md
07-ux-principles.md
08-motion-principles.md
09-security-policy.md

STAGE 6
design references
component reference
UI shell

STAGE 7
10-data-model.md
11-api-contracts.md

STAGE 8
12-testing-strategy.md
13-deployment.md
14-production-operations.md
15-dependency-policy.md
16-contribution-model.md

STAGE 9
repository bootstrap
CI
collaboration workflow

STAGE 10
vertical slices

STAGE 11
staging

STAGE 12
production

STAGE 13
operations

STAGE 14
continuous improvement

Understand before building.

Specify before implementing.

Research before selecting current technology.

Design the system before designing pages.

Generate references from product context.

Treat approved references as visual truth.

Use tokens instead of arbitrary styling.

Use canonical code instead of reinvention.

Use modules instead of folder chaos.

Use contracts before dependent work.

Use independent workspaces for independent changes.

Coordinate hotspots deliberately.

Prepare dependencies before parallel development.

Test at the correct layer.

Automate what machines can enforce.

Review what requires human judgment.

Never call unverified work complete.

Ship through CI and staging.

Operate production as part of the product.

Learn from every failure.

Keep the technology current through deliberate research.

GRILL ME

FINALIZE THE SPECIFICATION

RESEARCH THE CURRENT TECHNOLOGY BASELINE

BOOTSTRAP THE REPOSITORY

BUILD THE SYSTEM BEFORE BUILDING THE PRODUCT

BUILD THE PRODUCT INSIDE THE SYSTEM.