@williambeto/ai-workflow 1.19.1 → 2.2.0

package/templates/DESIGN.template.md

@@ -1,484 +0,0 @@
-# [Project Name] Design System
-
-## Purpose
-
-This file defines the visual design system for `[Project Name]`.
-
-AI coding agents should use this file when creating or updating user interfaces so that screens, components, layouts, and interactions stay visually consistent.
-
-This file follows the `DESIGN.md` idea: a single Markdown file in the project root that gives AI coding tools enough design context to build consistent UI using plain text, version-controlled design guidance. DESIGN.md commonly includes colors, typography, spacing, component patterns, elevation, and usage guidelines.
-
-## Design principles
-
-- **[Principle 1]**: [Short explanation]
-- **[Principle 2]**: [Short explanation]
-- **[Principle 3]**: [Short explanation]
-
-Example:
-
-- **Clarity first**: Interfaces should make the next action obvious.
-- **Consistency over novelty**: Reuse existing patterns before creating new ones.
-- **Accessible by default**: Color, layout, and interaction states must remain usable for keyboard and assistive technology users.
-
-## Brand personality
-
-Describe the product’s visual and emotional direction.
-
-- **Tone**: [Professional / playful / minimal / bold / calm / technical / premium]
-- **Density**: [Compact / balanced / spacious]
-- **Visual style**: [Flat / soft / elevated / editorial / dashboard-like / app-like]
-- **User feeling**: [What the interface should make users feel]
-
-## Color system
-
-DESIGN.md files should provide colors with usage guidance, not only raw values. The designmd.ai format describes colors as primary palette, neutrals, and semantic colors with hex values and usage notes.
-
-### Brand colors
-
-| Token           |      Hex | Usage                                             |
-| --------------- | -------: | ------------------------------------------------- |
-| `primary`       | `#[HEX]` | Main actions, links, active states                |
-| `primary-hover` | `#[HEX]` | Hover state for primary actions                   |
-| `primary-soft`  | `#[HEX]` | Subtle backgrounds, selected rows, light emphasis |
-| `secondary`     | `#[HEX]` | Secondary brand accent                            |
-| `accent`        | `#[HEX]` | Highlights, badges, decorative emphasis           |
-
-### Neutral colors
-
-| Token            |      Hex | Usage                               |
-| ---------------- | -------: | ----------------------------------- |
-| `background`     | `#[HEX]` | Main page background                |
-| `surface`        | `#[HEX]` | Cards, panels, containers           |
-| `surface-muted`  | `#[HEX]` | Secondary panels, muted areas       |
-| `border`         | `#[HEX]` | Default borders and dividers        |
-| `border-strong`  | `#[HEX]` | Stronger separators                 |
-| `text-primary`   | `#[HEX]` | Main readable text                  |
-| `text-secondary` | `#[HEX]` | Secondary text                      |
-| `text-muted`     | `#[HEX]` | Helper text, metadata, placeholders |
-
-### Semantic colors
-
-| Token          |      Hex | Usage                                |
-| -------------- | -------: | ------------------------------------ |
-| `success`      | `#[HEX]` | Success states and positive feedback |
-| `success-soft` | `#[HEX]` | Success backgrounds                  |
-| `warning`      | `#[HEX]` | Warning states                       |
-| `warning-soft` | `#[HEX]` | Warning backgrounds                  |
-| `danger`       | `#[HEX]` | Error states and destructive actions |
-| `danger-soft`  | `#[HEX]` | Error backgrounds                    |
-| `info`         | `#[HEX]` | Informational states                 |
-| `info-soft`    | `#[HEX]` | Informational backgrounds            |
-
-### Color usage rules
-
-- Use `primary` only for the main action in a section or screen.
-- Use semantic colors only for real semantic meaning.
-- Do not use color alone to communicate important information.
-- Keep contrast readable for text, buttons, inputs, and status labels.
-- Do not introduce new hex values unless the design system is updated.
-
-## Typography
-
-DESIGN.md should define font families, sizes, weights, line heights, and usage guidance.
-
-### Font families
-
-| Token          | Font                      | Usage                                |
-| -------------- | ------------------------- | ------------------------------------ |
-| `font-sans`    | `[Font name], sans-serif` | Main interface text                  |
-| `font-display` | `[Font name], sans-serif` | Large headings or marketing sections |
-| `font-mono`    | `[Font name], monospace`  | Code, IDs, technical values          |
-
-### Type scale
-
-| Token     |       Size | Line height |     Weight | Usage                         |
-| --------- | ---------: | ----------: | ---------: | ----------------------------- |
-| `display` | `[px/rem]` |  `[px/rem]` | `[weight]` | Hero titles                   |
-| `h1`      | `[px/rem]` |  `[px/rem]` | `[weight]` | Page titles                   |
-| `h2`      | `[px/rem]` |  `[px/rem]` | `[weight]` | Section titles                |
-| `h3`      | `[px/rem]` |  `[px/rem]` | `[weight]` | Card or subsection titles     |
-| `body`    | `[px/rem]` |  `[px/rem]` | `[weight]` | Main content                  |
-| `body-sm` | `[px/rem]` |  `[px/rem]` | `[weight]` | Secondary content             |
-| `caption` | `[px/rem]` |  `[px/rem]` | `[weight]` | Metadata, labels, helper text |
-
-### Typography rules
-
-- Use one clear `h1` per page.
-- Do not skip heading hierarchy for visual reasons.
-- Use `text-secondary` for supporting text, not low contrast.
-- Keep line length readable.
-- Use `font-mono` only for technical values, code, IDs, or logs.
-
-## Spacing
-
-DESIGN.md commonly includes a base spacing unit and scale values for consistent padding, margins, and gaps.
-
-### Base unit
-
-```txt
-Base spacing unit: [4px / 8px]
-```
-
-### Spacing scale
-
-| Token      |      Value | Usage                     |
-| ---------- | ---------: | ------------------------- |
-| `space-1`  | `[px/rem]` | Tight inline spacing      |
-| `space-2`  | `[px/rem]` | Small gaps                |
-| `space-3`  | `[px/rem]` | Form field gaps           |
-| `space-4`  | `[px/rem]` | Default component padding |
-| `space-6`  | `[px/rem]` | Section spacing           |
-| `space-8`  | `[px/rem]` | Large layout spacing      |
-| `space-12` | `[px/rem]` | Page-level spacing        |
-
-### Spacing rules
-
-- Use spacing tokens instead of one-off values.
-- Keep related elements visually grouped.
-- Increase vertical spacing between different sections.
-- Use consistent gaps in forms, cards, lists, and grids.
-- Avoid cramped interactive targets.
-
-## Layout
-
-### Containers
-
-| Token          |      Value | Usage                       |
-| -------------- | ---------: | --------------------------- |
-| `container-sm` | `[px/rem]` | Forms, narrow content       |
-| `container-md` | `[px/rem]` | Standard content            |
-| `container-lg` | `[px/rem]` | Dashboards and wide layouts |
-| `container-xl` | `[px/rem]` | Data-heavy screens          |
-
-### Grid
-
-- Use consistent column gaps.
-- Prefer responsive grids over fixed widths.
-- Avoid horizontal overflow on small screens.
-- Stack content vertically on mobile when needed.
-
-### Page structure
-
-Recommended order:
-
-1. Page header
-2. Primary action or summary
-3. Main content
-4. Supporting content
-5. Secondary actions or footer content
-
-## Radius
-
-| Token         |      Value | Usage                    |
-| ------------- | ---------: | ------------------------ |
-| `radius-sm`   | `[px/rem]` | Small controls, badges   |
-| `radius-md`   | `[px/rem]` | Inputs, buttons          |
-| `radius-lg`   | `[px/rem]` | Cards, panels            |
-| `radius-xl`   | `[px/rem]` | Large containers, modals |
-| `radius-full` |   `9999px` | Pills, avatars           |
-
-## Elevation
-
-DESIGN.md commonly includes elevation, shadows, glow effects, or depth cues for layered interfaces.
-
-| Token          | Value          | Usage                         |
-| -------------- | -------------- | ----------------------------- |
-| `shadow-sm`    | `[CSS shadow]` | Subtle elevation              |
-| `shadow-md`    | `[CSS shadow]` | Cards and dropdowns           |
-| `shadow-lg`    | `[CSS shadow]` | Modals, popovers              |
-| `shadow-focus` | `[CSS shadow]` | Focus ring or active emphasis |
-
-### Elevation rules
-
-- Use elevation to show hierarchy, not decoration.
-- Keep shadows consistent across similar components.
-- Do not combine heavy borders and heavy shadows unless intentional.
-- Modals and popovers should have stronger elevation than cards.
-
-## Borders
-
-| Token            | Value              | Usage                           |
-| ---------------- | ------------------ | ------------------------------- |
-| `border-default` | `1px solid #[HEX]` | Cards, inputs, dividers         |
-| `border-strong`  | `1px solid #[HEX]` | Active or emphasized containers |
-| `border-focus`   | `1px solid #[HEX]` | Focus or selected states        |
-
-## Components
-
-DESIGN.md should describe component patterns such as buttons, inputs, and cards with specific dimensions, colors, radius, padding, and usage rules.
-
-### Buttons
-
-#### Primary button
-
-Use for the main action.
-
-```txt
-Background: primary
-Text: white / high contrast
-Border: none
-Radius: radius-md
-Padding: [value]
-Font: body-sm / medium
-Hover: primary-hover
-Focus: visible focus ring
-Disabled: muted background, muted text, not clickable
-```
-
-Rules:
-
-- Use only one primary button per main section when possible.
-- Button labels must be action-oriented.
-- Do not use primary buttons for destructive actions.
-
-#### Secondary button
-
-Use for secondary actions.
-
-```txt
-Background: surface
-Text: text-primary
-Border: border-default
-Radius: radius-md
-Padding: [value]
-Hover: surface-muted
-Focus: visible focus ring
-```
-
-#### Destructive button
-
-Use only for destructive actions.
-
-```txt
-Background: danger
-Text: high contrast
-Hover: darker danger tone
-Confirmation: required for high-risk actions
-```
-
-### Inputs
-
-```txt
-Background: surface
-Text: text-primary
-Placeholder: text-muted
-Border: border-default
-Focus border: primary
-Error border: danger
-Radius: radius-md
-Padding: [value]
-Height: [value]
-```
-
-Rules:
-
-- Every input must have a visible label or accessible name.
-- Error messages must be specific and placed near the field.
-- Required fields must be clear.
-- Disabled fields must look disabled and remain readable.
-
-### Cards
-
-```txt
-Background: surface
-Border: border-default
-Radius: radius-lg
-Padding: space-4 / space-6
-Shadow: shadow-sm or none
-```
-
-Rules:
-
-- Cards should group related content.
-- Do not place unrelated actions in the same card.
-- Card headers should clearly describe the content.
-- Use consistent padding across cards.
-
-### Modals
-
-```txt
-Background: surface
-Radius: radius-xl
-Shadow: shadow-lg
-Max width: [value]
-Overlay: [color/opacity]
-Padding: space-6
-```
-
-Rules:
-
-- Modal must have a clear title.
-- Focus should move into the modal when opened.
-- Escape or close behavior should be clear.
-- Destructive modal actions need explicit confirmation.
-- Avoid modals for simple inline feedback.
-
-### Navigation
-
-Rules:
-
-- Active state must be visible.
-- Navigation labels must be short and clear.
-- Do not rely on icons without labels unless the pattern is already established.
-- Keyboard navigation must remain possible.
-
-### Tables and lists
-
-Rules:
-
-- Use clear column labels.
-- Align numbers consistently.
-- Provide empty states.
-- Provide loading states when data is fetched.
-- Avoid dense tables without spacing or hierarchy.
-- Preserve sorting, filtering, and pagination behavior when present.
-
-### Badges and status labels
-
-Rules:
-
-- Use semantic colors consistently.
-- Pair color with text.
-- Keep labels short.
-- Do not invent new status colors without updating the semantic color system.
-
-## States
-
-### Loading
-
-- Show clear progress or skeleton state for async content.
-- Avoid layout jumps where possible.
-- Do not block the whole page when only one section is loading.
-
-### Empty
-
-- Explain what is missing.
-- Provide the next useful action when available.
-- Keep tone neutral and helpful.
-
-### Error
-
-- Explain what failed.
-- Provide recovery action when possible.
-- Do not expose technical details to end users unless appropriate.
-
-### Success
-
-- Confirm what happened.
-- Avoid excessive success messages for routine actions.
-
-### Disabled
-
-- Disabled controls must have enough contrast.
-- Explain why an action is unavailable when not obvious.
-
-## Accessibility
-
-### Required baseline
-
-- Use semantic HTML when possible.
-- Use buttons for actions and links for navigation.
-- Provide labels for form controls.
-- Keep focus states visible.
-- Preserve keyboard navigation.
-- Do not communicate state by color alone.
-- Keep text contrast readable.
-- Use ARIA only when semantic HTML is insufficient.
-- Modals, dropdowns, and popovers must have reasonable focus behavior.
-
-## Responsive behavior
-
-### Breakpoints
-
-| Token |  Width | Usage          |
-| ----- | -----: | -------------- |
-| `sm`  | `[px]` | Small screens  |
-| `md`  | `[px]` | Tablets        |
-| `lg`  | `[px]` | Laptops        |
-| `xl`  | `[px]` | Large desktops |
-
-### Rules
-
-- Mobile layout should not require horizontal scrolling.
-- Touch targets should be comfortable.
-- Sidebars should collapse or adapt on small screens.
-- Tables should have a responsive strategy.
-- Long text should wrap safely.
-
-## Motion
-
-| Token           |      Value | Usage                    |
-| --------------- | ---------: | ------------------------ |
-| `duration-fast` |     `[ms]` | Hover and small feedback |
-| `duration-base` |     `[ms]` | Standard transitions     |
-| `duration-slow` |     `[ms]` | Large transitions        |
-| `ease-standard` | `[easing]` | Default easing           |
-
-Rules:
-
-- Motion should clarify state change.
-- Avoid excessive animation.
-- Respect reduced-motion preferences when possible.
-- Do not animate critical layout in a way that harms usability.
-
-## Content style
-
-### Voice
-
-- [Direct / friendly / technical / calm / premium / concise]
-
-### Rules
-
-- Use clear action labels.
-- Avoid vague button text like “Submit” when a specific action is possible.
-- Error messages should explain the problem and next step.
-- Empty states should help the user continue.
-- Keep labels consistent across screens.
-
-## Do and don't
-
-### Do
-
-- Use the defined color tokens.
-- Reuse existing components.
-- Keep spacing consistent.
-- Preserve accessibility basics.
-- Keep UI states explicit.
-- Follow the project’s established layout patterns.
-
-### Don't
-
-- Add random hex values.
-- Introduce a new styling system without approval.
-- Use color alone to indicate status.
-- Hide labels for important form fields.
-- Change product behavior during design cleanup.
-- Create one-off components when an existing pattern works.
-
-## Implementation guidance for AI agents
-
-When implementing UI:
-
-1. Read this file before editing UI code.
-2. Reuse the defined tokens and component patterns.
-3. Follow existing project components and framework conventions.
-4. Preserve behavior unless explicitly asked to change it.
-5. Validate responsive behavior when relevant.
-6. Validate accessibility basics when relevant.
-7. List any design tokens or patterns that are missing.
-8. Do not invent new visual rules silently.
-
-## Missing design decisions
-
-Use this section to track missing or unresolved design decisions.
-
-| Decision     | Status | Notes   |
-| ------------ | ------ | ------- |
-| [Decision 1] | Open   | [Notes] |
-| [Decision 2] | Open   | [Notes] |
-
-## Final instruction
-
-This file is the source of truth for visual implementation guidance.
-
-If the design system does not define a needed pattern, follow the closest existing pattern and document the assumption.

package/templates/PR-PLAN.template.md

@@ -1,172 +0,0 @@
-# Pull Request Plan
-
-## Title
-
-[Short, clear PR title]
-
-## Status
-
-Draft | Ready to implement | Needs clarification | Too broad | Blocked
-
-## Source inputs
-
-### Requirement
-
-[Reference the approved requirement]
-
-Example:
-
-```txt
-requirements/feature-name.md
-```
-
-### Functional specification
-
-[Reference the approved functional specification]
-
-Example:
-
-```txt
-specs/feature-name.md
-```
-
-### Technical plan
-
-[Reference the approved technical plan]
-
-Example:
-
-```txt
-tech-plans/feature-name.md
-```
-
-## Objective
-
-[One sentence describing the goal of this PR]
-
-## Context
-
-[Brief explanation of why this PR is needed]
-
-## Scope
-
-### Included
-
-- [Item included in this PR]
-- [Item included in this PR]
-
-### Not included
-
-- [Item explicitly out of scope for this PR]
-- [Item explicitly out of scope for this PR]
-
-## Expected files
-
-- `path/to/file` — [expected change]
-- `path/to/file` — [expected change]
-
-## Files that should not change
-
-- `path/to/file` — [reason]
-- `path/to/file` — [reason]
-
-Use `Not applicable` if there are no specific files that must be protected.
-
-## Behavior preserved
-
-- [Existing behavior that must remain unchanged]
-- [Existing behavior that must remain unchanged]
-
-## Behavior changed
-
-- [Behavior intentionally changed by this PR]
-
-Use `None expected` if this PR should not change existing behavior.
-
-## Acceptance criteria
-
-### Criterion 1
-
-[Specific, testable criterion]
-
-### Criterion 2
-
-[Specific, testable criterion]
-
-## Implementation notes
-
-- [Relevant implementation note]
-- [Relevant implementation note]
-
-Keep this section short. Do not include full implementation code.
-
-## Validation plan
-
-### Automated checks
-
-- `command`
-- `command`
-
-Examples:
-
-```bash
-npm run lint
-npm run typecheck
-npm test
-npm run build
-```
-
-Use project-specific commands when available.
-
-### Manual checks
-
-- [Manual check 1]
-- [Manual check 2]
-
-### Not covered
-
-- [Area not covered] — [reason]
-
-Use `None known` if all relevant areas are covered.
-
-## Regression risks
-
-| Risk     | Severity            | Impact   | Mitigation   |
-| -------- | ------------------- | -------- | ------------ |
-| [Risk 1] | High / Medium / Low | [Impact] | [Mitigation] |
-| [Risk 2] | High / Medium / Low | [Impact] | [Mitigation] |
-
-## Dependencies
-
-- [Previous PR, decision, file, service, environment, or external dependency]
-
-Use `None` if there are no dependencies.
-
-## Rollback notes
-
-- [How this PR can be reverted or recovered from if needed]
-
-Use `Not applicable` for documentation-only or low-risk changes.
-
-## Assumptions
-
-- [Assumption 1]
-- [Assumption 2]
-
-Assumptions must not be treated as confirmed facts.
-
-## Open questions
-
-- [Question 1]
-- [Question 2]
-
-Use `None` only when there are no relevant open questions.
-
-## Out of scope
-
-- [Explicitly excluded item]
-- [Explicitly excluded item]
-
-## Final recommendation
-
-Ready to implement | Needs clarification | Too broad | Blocked