From dbecc041e90bd80c454565e4c677461756146ba7 Mon Sep 17 00:00:00 2001 From: Malek-Ghorbel <79011129+Malek-Ghorbel@users.noreply.github.com> Date: Wed, 30 Sep 2026 18:57:28 +0200 Subject: [PATCH] chore: add shared agent skills --- .../skills/agent-stack-v5-minimal/MANIFEST.md | 16 +++ .../skills/agent-stack-v5-minimal/README.md | 82 ++++++++++++ .../agent-stack-v5-minimal/README_FIRST.md | 54 ++++++++ .../agent-stack-v5-minimal/docs/SOURCES.md | 11 ++ .../skills/agent-stack-v5-minimal/install.ps1 | 64 ++++++++++ .../skills/agent-stack-v5-minimal/install.sh | 74 +++++++++++ .../agent-stack-v5-minimal/profiles/coding.md | 2 + .../profiles/syntaro.md | 2 + .../schemas/implementation.schema.json | 16 +++ .../schemas/plan.schema.json | 24 ++++ .../schemas/verification.schema.json | 17 +++ .../scripts/build_work_bundles.py | 21 +++ .../agent-stack-v5-minimal/scripts/doctor.py | 23 ++++ .../scripts/install_core.py | 61 +++++++++ .../scripts/select_profile.py | 5 + .../skills/executor/SKILL.md | 86 +++++++++++++ .../skills/planner/SKILL.md | 110 ++++++++++++++++ .../skills/verifier/SKILL.md | 107 ++++++++++++++++ .../templates/AGENTS.block.md | 26 ++++ .../templates/OMP_RULES.md | 11 ++ .../templates/WORK_PROJECT_INSTRUCTIONS.md | 15 +++ .agents/skills/coding-control-plane/SKILL.md | 120 ++++++++++++++++++ .../coding-control-plane/agents/openai.yaml | 15 +++ .../coding-control-plane/assets/icon.svg | 6 + .../assets/plan-template.md | 34 +++++ .../assets/verification-template.md | 20 +++ .../references/anti-loop-rules.md | 13 ++ .agents/skills/executor/SKILL.md | 86 +++++++++++++ .agents/skills/planner/SKILL.md | 110 ++++++++++++++++ .agents/skills/ui-ux-curated-full/MANIFEST.md | 49 +++++++ .agents/skills/ui-ux-curated-full/SKILL.md | 39 ++++++ .../ui-ux-curated-full/agents/openai.yaml | 16 +++ .../skills/ui-ux-curated-full/assets/icon.svg | 8 ++ .../checklists/pre-delivery.md | 11 ++ .../checklists/pre-implementation.md | 10 ++ .../checklists/screenshot-review.md | 2 + .../presets/dark-glass.json | 13 ++ .../presets/glass-neutral.json | 18 +++ .../presets/liquid-blue.json | 16 +++ .../presets/liquid-warm.json | 15 +++ .../references/accessibility.md | 5 + .../references/anti-generic-ai-ui.md | 5 + .../references/chat-assistant.md | 5 + .../references/color-and-contrast.md | 5 + .../references/dashboards.md | 5 + .../references/density-and-spacing.md | 5 + .../references/interaction-and-motion.md | 5 + .../references/mobile-first.md | 5 + .../references/nuxt-vue-tailwind.md | 5 + .../references/planning-verification.md | 5 + .../references/product-ui-patterns.md | 5 + .../references/responsive.md | 5 + .../references/typography.md | 5 + .../references/ux-foundations.md | 7 + .../ui-ux-curated-full/snippets/glass.css | 10 ++ .../snippets/liquid-glass.css | 12 ++ .../snippets/liquid-morph.css | 2 + .../snippets/tailwind-patterns.md | 2 + .../ui-ux-curated-full/snippets/tokens.css | 8 ++ .../styles/glassmorphism-dashboard.md | 5 + .../styles/glassmorphism.md | 7 + .../styles/liquid-glass-mobile.md | 5 + .../ui-ux-curated-full/styles/liquid-glass.md | 5 + .../styles/liquid-morph-assistant.md | 5 + .../ui-ux-curated-full/styles/liquid-morph.md | 5 + .../templates/assistant-panel.md | 2 + .../templates/command-palette.md | 2 + .../templates/dashboard-shell.md | 4 + .../templates/design-system-master.md | 14 ++ .../templates/detail-drawer.md | 2 + .../templates/empty-state.md | 2 + .../ui-ux-curated-full/templates/form-flow.md | 2 + .../templates/mobile-bottom-sheet.md | 2 + .../templates/page-override.md | 9 ++ .../templates/planner-screen.md | 2 + .../templates/settings-page.md | 2 + .../templates/table-toolbar.md | 2 + .../templates/ui-contract.md | 20 +++ .../templates/verifier-screen.md | 2 + .agents/skills/ui-visual-verifier/SKILL.md | 54 ++++++++ .../ui-visual-verifier/agents/openai.yaml | 15 +++ .../skills/ui-visual-verifier/assets/icon.svg | 8 ++ .../assets/ui-review-report.md | 15 +++ .../references/defect-taxonomy.md | 36 ++++++ .agents/skills/verifier/SKILL.md | 107 ++++++++++++++++ 85 files changed, 1868 insertions(+) create mode 100644 .agents/skills/agent-stack-v5-minimal/MANIFEST.md create mode 100644 .agents/skills/agent-stack-v5-minimal/README.md create mode 100644 .agents/skills/agent-stack-v5-minimal/README_FIRST.md create mode 100644 .agents/skills/agent-stack-v5-minimal/docs/SOURCES.md create mode 100644 .agents/skills/agent-stack-v5-minimal/install.ps1 create mode 100644 .agents/skills/agent-stack-v5-minimal/install.sh create mode 100644 .agents/skills/agent-stack-v5-minimal/profiles/coding.md create mode 100644 .agents/skills/agent-stack-v5-minimal/profiles/syntaro.md create mode 100644 .agents/skills/agent-stack-v5-minimal/schemas/implementation.schema.json create mode 100644 .agents/skills/agent-stack-v5-minimal/schemas/plan.schema.json create mode 100644 .agents/skills/agent-stack-v5-minimal/schemas/verification.schema.json create mode 100644 .agents/skills/agent-stack-v5-minimal/scripts/build_work_bundles.py create mode 100644 .agents/skills/agent-stack-v5-minimal/scripts/doctor.py create mode 100644 .agents/skills/agent-stack-v5-minimal/scripts/install_core.py create mode 100644 .agents/skills/agent-stack-v5-minimal/scripts/select_profile.py create mode 100644 .agents/skills/agent-stack-v5-minimal/skills/executor/SKILL.md create mode 100644 .agents/skills/agent-stack-v5-minimal/skills/planner/SKILL.md create mode 100644 .agents/skills/agent-stack-v5-minimal/skills/verifier/SKILL.md create mode 100644 .agents/skills/agent-stack-v5-minimal/templates/AGENTS.block.md create mode 100644 .agents/skills/agent-stack-v5-minimal/templates/OMP_RULES.md create mode 100644 .agents/skills/agent-stack-v5-minimal/templates/WORK_PROJECT_INSTRUCTIONS.md create mode 100644 .agents/skills/coding-control-plane/SKILL.md create mode 100644 .agents/skills/coding-control-plane/agents/openai.yaml create mode 100644 .agents/skills/coding-control-plane/assets/icon.svg create mode 100644 .agents/skills/coding-control-plane/assets/plan-template.md create mode 100644 .agents/skills/coding-control-plane/assets/verification-template.md create mode 100644 .agents/skills/coding-control-plane/references/anti-loop-rules.md create mode 100644 .agents/skills/executor/SKILL.md create mode 100644 .agents/skills/planner/SKILL.md create mode 100644 .agents/skills/ui-ux-curated-full/MANIFEST.md create mode 100644 .agents/skills/ui-ux-curated-full/SKILL.md create mode 100644 .agents/skills/ui-ux-curated-full/agents/openai.yaml create mode 100644 .agents/skills/ui-ux-curated-full/assets/icon.svg create mode 100644 .agents/skills/ui-ux-curated-full/checklists/pre-delivery.md create mode 100644 .agents/skills/ui-ux-curated-full/checklists/pre-implementation.md create mode 100644 .agents/skills/ui-ux-curated-full/checklists/screenshot-review.md create mode 100644 .agents/skills/ui-ux-curated-full/presets/dark-glass.json create mode 100644 .agents/skills/ui-ux-curated-full/presets/glass-neutral.json create mode 100644 .agents/skills/ui-ux-curated-full/presets/liquid-blue.json create mode 100644 .agents/skills/ui-ux-curated-full/presets/liquid-warm.json create mode 100644 .agents/skills/ui-ux-curated-full/references/accessibility.md create mode 100644 .agents/skills/ui-ux-curated-full/references/anti-generic-ai-ui.md create mode 100644 .agents/skills/ui-ux-curated-full/references/chat-assistant.md create mode 100644 .agents/skills/ui-ux-curated-full/references/color-and-contrast.md create mode 100644 .agents/skills/ui-ux-curated-full/references/dashboards.md create mode 100644 .agents/skills/ui-ux-curated-full/references/density-and-spacing.md create mode 100644 .agents/skills/ui-ux-curated-full/references/interaction-and-motion.md create mode 100644 .agents/skills/ui-ux-curated-full/references/mobile-first.md create mode 100644 .agents/skills/ui-ux-curated-full/references/nuxt-vue-tailwind.md create mode 100644 .agents/skills/ui-ux-curated-full/references/planning-verification.md create mode 100644 .agents/skills/ui-ux-curated-full/references/product-ui-patterns.md create mode 100644 .agents/skills/ui-ux-curated-full/references/responsive.md create mode 100644 .agents/skills/ui-ux-curated-full/references/typography.md create mode 100644 .agents/skills/ui-ux-curated-full/references/ux-foundations.md create mode 100644 .agents/skills/ui-ux-curated-full/snippets/glass.css create mode 100644 .agents/skills/ui-ux-curated-full/snippets/liquid-glass.css create mode 100644 .agents/skills/ui-ux-curated-full/snippets/liquid-morph.css create mode 100644 .agents/skills/ui-ux-curated-full/snippets/tailwind-patterns.md create mode 100644 .agents/skills/ui-ux-curated-full/snippets/tokens.css create mode 100644 .agents/skills/ui-ux-curated-full/styles/glassmorphism-dashboard.md create mode 100644 .agents/skills/ui-ux-curated-full/styles/glassmorphism.md create mode 100644 .agents/skills/ui-ux-curated-full/styles/liquid-glass-mobile.md create mode 100644 .agents/skills/ui-ux-curated-full/styles/liquid-glass.md create mode 100644 .agents/skills/ui-ux-curated-full/styles/liquid-morph-assistant.md create mode 100644 .agents/skills/ui-ux-curated-full/styles/liquid-morph.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/assistant-panel.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/command-palette.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/dashboard-shell.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/design-system-master.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/detail-drawer.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/empty-state.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/form-flow.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/mobile-bottom-sheet.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/page-override.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/planner-screen.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/settings-page.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/table-toolbar.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/ui-contract.md create mode 100644 .agents/skills/ui-ux-curated-full/templates/verifier-screen.md create mode 100644 .agents/skills/ui-visual-verifier/SKILL.md create mode 100644 .agents/skills/ui-visual-verifier/agents/openai.yaml create mode 100644 .agents/skills/ui-visual-verifier/assets/icon.svg create mode 100644 .agents/skills/ui-visual-verifier/assets/ui-review-report.md create mode 100644 .agents/skills/ui-visual-verifier/references/defect-taxonomy.md create mode 100644 .agents/skills/verifier/SKILL.md diff --git a/.agents/skills/agent-stack-v5-minimal/MANIFEST.md b/.agents/skills/agent-stack-v5-minimal/MANIFEST.md new file mode 100644 index 0000000..6fade47 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/MANIFEST.md @@ -0,0 +1,16 @@ +# Manifest + +## Skills authored by this package (exactly 3) + +- `skills/planner/SKILL.md` +- `skills/executor/SKILL.md` +- `skills/verifier/SKILL.md` + +## Upstream skills/capabilities installed by `install.sh` / `install.ps1` + +- `ui-ux-pro-max` — nextlevelbuilder/ui-ux-pro-max-skill +- `impeccable` — pbakaus/impeccable +- `graphify` — Graphify-Labs/graphify +- `archify` — tt-a1i/archify + +Schemas, profiles, policies, and scripts are support files, not skills. diff --git a/.agents/skills/agent-stack-v5-minimal/README.md b/.agents/skills/agent-stack-v5-minimal/README.md new file mode 100644 index 0000000..cef1a2d --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/README.md @@ -0,0 +1,82 @@ +# Agent Stack v5 Minimal + +## Why this shape + +The stack is deliberately small. We do not maintain our own copies of debugging, regression, UI, architecture, or repo-search methodologies as separate skills. Those rules live inside the three role wrappers, while specialized capability is delegated to upstream tools. + +### Owned skills + +1. **planner** — evidence-first plan, architecture/UI impact, acceptance and verification contract. +2. **executor** — plan adherence, coherent implementation, root-cause-first failure handling, hard anti-loop stop. +3. **verifier** — independent requirement/regression/architecture/rendered-UI verification. + +### Upstream capabilities + +- **Graphify**: persistent local code graph. The official Python package is `graphifyy`; CLI command is `graphify`. +- **Archify**: source-backed architecture/workflow/data-flow diagrams and validation. +- **UI UX Pro Max**: real design datasets/templates/search tooling installed under `.agents/skills/`. +- **Impeccable**: one UI design skill, rendered/live workflows, deterministic detector suite and Codex hook. + +## Target layout after installation + +```text +repo/ +├── AGENTS.md +├── .omp/RULES.md +├── .agents/skills/ +│ ├── planner/ # ours +│ ├── executor/ # ours +│ ├── verifier/ # ours +│ ├── graphify/ # upstream +│ ├── archify/ # upstream +│ ├── ui-ux-pro-max/ # upstream +│ └── impeccable/ # upstream +├── .agent-stack/ +│ ├── profile +│ ├── schemas/ +│ └── chatgpt-work/ +├── .codex/hooks.json # installed by Impeccable for Codex +└── graphify-out/ # graph data +``` + +OMP natively discovers `.agents/skills/`, so the same skill library works for OMP and Codex without duplicate authored skills. + +## Usage + +You normally do not invoke every capability manually. Give the task as normal. The role wrappers decide when Graphify/Archify/UI UX Pro Max/Impeccable are needed. + +Manual phase testing is still possible: +- `$planner`, `$executor`, `$verifier` in Codex-style skill invocation; +- `/skill:planner`, `/skill:executor`, `/skill:verifier` in OMP. + +### UI flow + +`planner -> UI UX Pro Max -> UI contract -> executor -> rendered UI -> Impeccable -> verifier` + +### Anti-loop flow + +First unexpected regression: reproduce and prove root cause before another edit. +Second unexpected regression: stop and replan. + +## ChatGPT Work + +The installer builds one ZIP per installed skill under: + +`.agent-stack/chatgpt-work/upload-ready/` + +ChatGPT supports uploaded Skills. Upload the skills you want in ChatGPT's Skills UI. The repository also gets `.agent-stack/chatgpt-work/PROJECT_INSTRUCTIONS.md`, which can be pasted into project instructions or used as the workflow reference when Work operates on a local folder. + +## Updating upstream capabilities + +Re-run the installer, or update individually: + +```bash +npx -y ui-ux-pro-max-cli@latest init --ai universal --force +npx -y impeccable update +npx -y skills add tt-a1i/archify --skill archify --agent codex --copy --yes +uv tool install --upgrade graphifyy +graphify install --project --platform agents +graphify hook install +``` + +After an Impeccable update, Codex may ask you to approve the updated hook again. diff --git a/.agents/skills/agent-stack-v5-minimal/README_FIRST.md b/.agents/skills/agent-stack-v5-minimal/README_FIRST.md new file mode 100644 index 0000000..04625e9 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/README_FIRST.md @@ -0,0 +1,54 @@ +# Agent Stack v5 Minimal — start here + +This is the corrected minimal version: **3 skills we own + 4 upstream capabilities**. + +We own only: +- `planner` +- `executor` +- `verifier` + +Installed upstream: +- Graphify — repo graph / dependency grounding +- Archify — architecture and flow modeling +- UI UX Pro Max — UI/UX design intelligence and templates +- Impeccable — rendered UI review, deterministic detectors, design workflow + +Nothing else is authored as a skill. Schemas, policies, profile files and installer scripts are not skills. + +## Install + +From the target repository: + +```bash +/path/to/agent-stack-v5-minimal/install.sh . +``` + +Windows PowerShell: + +```powershell +& "C:\path\to\agent-stack-v5-minimal\install.ps1" -Target . +``` + +The installer is project-local where possible so OMP and Codex see the same `.agents/skills/` library. + +## After install + +For Impeccable, initialize the product/design context once inside your harness. In Codex use `$impeccable init`; in OMP invoke the Impeccable skill and run its `init` flow. In Codex, approve the project hook once via `/hooks`. + +Then use your coding agent normally. For non-trivial changes, `AGENTS.md` enforces: + +`planner -> executor -> verifier` + +## Syntaro mode + +Same skills, stricter policy: + +```bash +python3 .agent-stack/bin/select_profile.py syntaro +``` + +Switch back: + +```bash +python3 .agent-stack/bin/select_profile.py coding +``` diff --git a/.agents/skills/agent-stack-v5-minimal/docs/SOURCES.md b/.agents/skills/agent-stack-v5-minimal/docs/SOURCES.md new file mode 100644 index 0000000..c829396 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/docs/SOURCES.md @@ -0,0 +1,11 @@ +# Upstream install references + +Verified against upstream documentation on 2026-09-28. + +- UI UX Pro Max: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill +- Impeccable: https://github.com/pbakaus/impeccable +- Graphify: https://github.com/Graphify-Labs/graphify +- Archify: https://github.com/tt-a1i/archify +- OMP skills discovery: https://github.com/can1357/oh-my-pi/blob/main/docs/skills.md +- ChatGPT Skills: https://help.openai.com/en/articles/20001066-skills-in-chatgpt +- ChatGPT Work and Codex: https://help.openai.com/en/articles/20001275-chatgpt-work-and-codex diff --git a/.agents/skills/agent-stack-v5-minimal/install.ps1 b/.agents/skills/agent-stack-v5-minimal/install.ps1 new file mode 100644 index 0000000..a9dee91 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/install.ps1 @@ -0,0 +1,64 @@ +param( + [string]$Target = ".", + [ValidateSet("coding","syntaro")][string]$Profile = "coding" +) +$ErrorActionPreference = "Stop" +$Root = Split-Path -Parent $MyInvocation.MyCommand.Path +$Target = (Resolve-Path $Target).Path + +function Need($cmd) { + if (-not (Get-Command $cmd -ErrorAction SilentlyContinue)) { throw "Missing required command: $cmd" } +} +Need python +Need node +Need npx + +Write-Host "`n[1/7] Installing minimal owned control plane..." +python "$Root\scripts\install_core.py" --target "$Target" --profile "$Profile" +Set-Location $Target + +Write-Host "`n[2/7] Installing UI UX Pro Max..." +npx -y ui-ux-pro-max-cli@latest init --ai universal --force + +Write-Host "`n[3/7] Installing Impeccable..." +npx -y impeccable install --providers=codex --scope=project + +Write-Host "`n[4/7] Installing Archify..." +npx -y skills add tt-a1i/archify --skill archify --agent codex --copy --yes + +Write-Host "`n[5/7] Installing Graphify..." +if (Get-Command uv -ErrorAction SilentlyContinue) { + uv tool install --upgrade graphifyy | Out-Host +} elseif (Get-Command pipx -ErrorAction SilentlyContinue) { + pipx install graphifyy | Out-Host +} else { + throw "Install uv first (recommended: winget install astral-sh.uv) or install pipx, then rerun." +} +if (-not (Get-Command graphify -ErrorAction SilentlyContinue)) { + throw "graphify is not on PATH yet. Open a new PowerShell (or update PATH) and rerun." +} +graphify install --project --platform agents + +Write-Host "`n[6/7] Building repository graph + hook..." +graphify . +graphify hook install + +Write-Host "`n[7/7] Building ChatGPT Work bundles + doctor..." +python "$Root\scripts\build_work_bundles.py" --target "$Target" +python "$Root\scripts\doctor.py" --target "$Target" + +Write-Host @" + +DONE. + +One-time UI setup: + OMP: invoke impeccable and run init + Codex: `$impeccable init +Codex: open /hooks once and approve the Impeccable project hook. + +Switch Syntaro profile: + python .agent-stack/bin/select_profile.py syntaro + +ChatGPT Work bundles: + .agent-stack/chatgpt-work/upload-ready/ +"@ diff --git a/.agents/skills/agent-stack-v5-minimal/install.sh b/.agents/skills/agent-stack-v5-minimal/install.sh new file mode 100644 index 0000000..06fe33f --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/install.sh @@ -0,0 +1,74 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET="${1:-.}" +PROFILE="${PROFILE:-coding}" +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +TARGET="$(cd "$TARGET" && pwd)" + +need() { command -v "$1" >/dev/null 2>&1 || { echo "Missing required command: $1" >&2; exit 1; }; } +need python3 +need node +need npx + +printf '\n[1/7] Installing minimal owned control plane...\n' +python3 "$ROOT/scripts/install_core.py" --target "$TARGET" --profile "$PROFILE" + +cd "$TARGET" + +printf '\n[2/7] Installing UI UX Pro Max into .agents/skills...\n' +npx -y ui-ux-pro-max-cli@latest init --ai universal --force + +printf '\n[3/7] Installing Impeccable for Codex-compatible .agents/skills + Codex hook...\n' +npx -y impeccable install --providers=codex --scope=project + +printf '\n[4/7] Installing Archify project skill...\n' +npx -y skills add tt-a1i/archify --skill archify --agent codex --copy --yes + +printf '\n[5/7] Installing Graphify CLI + project Agent Skill...\n' +if command -v uv >/dev/null 2>&1; then + uv tool install --upgrade graphifyy >/dev/null +elif command -v pipx >/dev/null 2>&1; then + if pipx list 2>/dev/null | grep -q 'graphifyy'; then pipx upgrade graphifyy >/dev/null; else pipx install graphifyy >/dev/null; fi +else + echo "Neither uv nor pipx found. Install one, then rerun:" >&2 + echo " uv: https://docs.astral.sh/uv/getting-started/installation/" >&2 + echo " pipx: python3 -m pip install --user pipx && python3 -m pipx ensurepath" >&2 + exit 1 +fi + +if ! command -v graphify >/dev/null 2>&1; then + echo "graphify was installed but is not yet on PATH. Open a new shell or run 'uv tool update-shell', then rerun install.sh." >&2 + exit 1 +fi +graphify install --project --platform agents + +printf '\n[6/7] Building initial repository graph and installing update hook...\n' +graphify . +graphify hook install + +printf '\n[7/7] Building ChatGPT Work upload bundles and running doctor...\n' +python3 "$ROOT/scripts/build_work_bundles.py" --target "$TARGET" +python3 "$ROOT/scripts/doctor.py" --target "$TARGET" || true + +cat <<'TXT' + +DONE. + +One-time UI setup inside your coding harness: + OMP: /skill:impeccable init (or invoke the impeccable skill and ask it to init) + Codex: $impeccable init + +Codex only: open /hooks once and approve the project Impeccable hook. + +Normal workflow: give the coding task normally. AGENTS.md tells the agent to use +planner -> executor -> verifier for non-trivial work. + +Switch Syntaro profile: + python3 .agent-stack/bin/select_profile.py syntaro + +ChatGPT Work upload bundles: + .agent-stack/chatgpt-work/upload-ready/ +Project instructions: + .agent-stack/chatgpt-work/PROJECT_INSTRUCTIONS.md +TXT diff --git a/.agents/skills/agent-stack-v5-minimal/profiles/coding.md b/.agents/skills/agent-stack-v5-minimal/profiles/coding.md new file mode 100644 index 0000000..25013c2 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/profiles/coding.md @@ -0,0 +1,2 @@ +# coding +Default profile for normal software delivery. Plan enough to avoid rework, execute tightly, and independently verify before completion. diff --git a/.agents/skills/agent-stack-v5-minimal/profiles/syntaro.md b/.agents/skills/agent-stack-v5-minimal/profiles/syntaro.md new file mode 100644 index 0000000..9039d47 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/profiles/syntaro.md @@ -0,0 +1,2 @@ +# syntaro +Planning/verification-heavy profile. Explicitly surface missing evidence and human decisions; require requirement-to-evidence mapping and architecture/verification readiness before completion. diff --git a/.agents/skills/agent-stack-v5-minimal/schemas/implementation.schema.json b/.agents/skills/agent-stack-v5-minimal/schemas/implementation.schema.json new file mode 100644 index 0000000..c51cab1 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/schemas/implementation.schema.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "ImplementationArtifact", + "type": "object", + "required": ["requirements_implemented", "changed_files", "checks", "deviations", "status"], + "properties": { + "requirements_implemented": {"type": "array", "items": {"type": "string"}}, + "changed_files": {"type": "array", "items": {"type": "string"}}, + "checks": {"type": "array", "items": {"type": "object", "properties": {"command": {"type": "string"}, "result": {"type": "string"}}}}, + "deviations": {"type": "array", "items": {"type": "string"}}, + "unexpected_failures": {"type": "array", "items": {"type": "object", "properties": {"failure": {"type": "string"}, "cause": {"type": "string"}, "evidence": {"type": "string"}}}}, + "known_limitations": {"type": "array", "items": {"type": "string"}}, + "verifier_evidence": {"type": "array", "items": {"type": "string"}}, + "status": {"enum": ["IMPLEMENTED_FOR_VERIFICATION", "REPLAN", "HUMAN_DECISION"]} + } +} diff --git a/.agents/skills/agent-stack-v5-minimal/schemas/plan.schema.json b/.agents/skills/agent-stack-v5-minimal/schemas/plan.schema.json new file mode 100644 index 0000000..2b985fd --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/schemas/plan.schema.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "PlanArtifact", + "type": "object", + "required": ["goal", "requirements", "affected_components", "invariants", "implementation_steps", "acceptance_criteria", "verification_plan", "regression_surface", "status"], + "properties": { + "goal": {"type": "string"}, + "requirements": {"type": "array", "items": {"type": "object", "required": ["id", "text"], "properties": {"id": {"type": "string"}, "text": {"type": "string"}}}}, + "evidence_consulted": {"type": "array", "items": {"type": "string"}}, + "affected_components": {"type": "array", "items": {"type": "string"}}, + "invariants": {"type": "array", "items": {"type": "string"}}, + "assumptions": {"type": "array", "items": {"type": "object", "properties": {"assumption": {"type": "string"}, "validation": {"type": "string"}}}}, + "architecture_impact": {"type": "string"}, + "implementation_steps": {"type": "array", "items": {"type": "string"}}, + "acceptance_criteria": {"type": "array", "items": {"type": "object", "required": ["id", "requirement_id", "criterion"], "properties": {"id": {"type": "string"}, "requirement_id": {"type": "string"}, "criterion": {"type": "string"}}}}, + "verification_plan": {"type": "array", "items": {"type": "string"}}, + "regression_surface": {"type": "array", "items": {"type": "string"}}, + "ui_contract": {"type": ["object", "null"]}, + "open_decisions": {"type": "array", "items": {"type": "string"}}, + "missing_evidence": {"type": "array", "items": {"type": "string"}}, + "non_goals": {"type": "array", "items": {"type": "string"}}, + "status": {"enum": ["PLAN_READY", "NEEDS_EVIDENCE", "HUMAN_DECISION"]} + } +} diff --git a/.agents/skills/agent-stack-v5-minimal/schemas/verification.schema.json b/.agents/skills/agent-stack-v5-minimal/schemas/verification.schema.json new file mode 100644 index 0000000..0a05f2f --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/schemas/verification.schema.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "VerificationArtifact", + "type": "object", + "required": ["criteria", "regressions", "scope_review", "status"], + "properties": { + "criteria": {"type": "array", "items": {"type": "object", "required": ["id", "status", "evidence"], "properties": {"id": {"type": "string"}, "status": {"enum": ["PASS", "FAIL", "UNPROVEN"]}, "evidence": {"type": "array", "items": {"type": "string"}}}}}, + "regressions": {"type": "array", "items": {"type": "string"}}, + "architecture_compliance": {"type": "string"}, + "scope_review": {"type": "array", "items": {"type": "string"}}, + "ui_evidence": {"type": "array", "items": {"type": "string"}}, + "missing_evidence": {"type": "array", "items": {"type": "string"}}, + "open_decisions": {"type": "array", "items": {"type": "string"}}, + "status": {"enum": ["READY", "FIX_LOCAL", "REPLAN", "HUMAN_DECISION"]}, + "next_action": {"type": "string"} + } +} diff --git a/.agents/skills/agent-stack-v5-minimal/scripts/build_work_bundles.py b/.agents/skills/agent-stack-v5-minimal/scripts/build_work_bundles.py new file mode 100644 index 0000000..0e6ef75 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/scripts/build_work_bundles.py @@ -0,0 +1,21 @@ +#!/usr/bin/env python3 +from __future__ import annotations +import argparse, zipfile +from pathlib import Path + +def zip_skill(src: Path, dest: Path): + with zipfile.ZipFile(dest,'w',zipfile.ZIP_DEFLATED) as z: + for p in sorted(src.rglob('*')): + if p.is_file(): z.write(p,p.relative_to(src)) + +def main(): + ap=argparse.ArgumentParser(); ap.add_argument('--target',default='.') + a=ap.parse_args(); root=Path(a.target).resolve(); skills=root/'.agents'/'skills'; out=root/'.agent-stack'/'chatgpt-work'/'upload-ready'; out.mkdir(parents=True,exist_ok=True) + made=[] + if skills.exists(): + for d in sorted(skills.iterdir()): + if d.is_dir() and (d/'SKILL.md').exists(): + dest=out/f'{d.name}.zip'; zip_skill(d,dest); made.append(dest) + print(f'Created {len(made)} ChatGPT skill bundles in {out}') + for p in made: print(' -',p.name) +if __name__=='__main__': main() diff --git a/.agents/skills/agent-stack-v5-minimal/scripts/doctor.py b/.agents/skills/agent-stack-v5-minimal/scripts/doctor.py new file mode 100644 index 0000000..5e7df5d --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/scripts/doctor.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +from __future__ import annotations +import argparse, json, shutil +from pathlib import Path +ap=argparse.ArgumentParser(); ap.add_argument('--target',default='.'); a=ap.parse_args(); root=Path(a.target).resolve() +checks=[] +def add(name,ok,detail=''): checks.append((name,ok,detail)) +for name in ('planner','executor','verifier','ui-ux-pro-max','impeccable','graphify','archify'): + p=root/'.agents'/'skills'/name/'SKILL.md'; add(f'skill:{name}',p.exists(),str(p)) +add('AGENTS.md',(root/'AGENTS.md').exists()) +add('OMP sticky rules',(root/'.omp'/'RULES.md').exists()) +for name in ('plan.schema.json','implementation.schema.json','verification.schema.json'): + p=root/'.agent-stack'/'schemas'/name + ok=False + if p.exists(): + try: json.loads(p.read_text()); ok=True + except Exception: pass + add('schema:'+name,ok) +for cmd in ('node','npx','graphify'): + add('command:'+cmd,shutil.which(cmd) is not None,shutil.which(cmd) or 'not on PATH') +for n,ok,d in checks: print(('OK ' if ok else 'MISS'),n,('— '+d if d else '')) +missing=[x for x in checks if not x[1]] +raise SystemExit(1 if missing else 0) diff --git a/.agents/skills/agent-stack-v5-minimal/scripts/install_core.py b/.agents/skills/agent-stack-v5-minimal/scripts/install_core.py new file mode 100644 index 0000000..28d367c --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/scripts/install_core.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +from __future__ import annotations +import argparse, shutil +from pathlib import Path + +START='' +END='' + +def merge_block(path: Path, block: str): + path.parent.mkdir(parents=True, exist_ok=True) + old = path.read_text(encoding='utf-8') if path.exists() else '' + if START in old and END in old: + a=old.index(START); b=old.index(END)+len(END) + new=old[:a].rstrip()+('\n\n' if old[:a].strip() else '')+block.strip()+('\n\n'+old[b:].lstrip() if old[b:].strip() else '\n') + else: + new=old.rstrip()+('\n\n' if old.strip() else '')+block.strip()+'\n' + path.write_text(new, encoding='utf-8') + +def main(): + ap=argparse.ArgumentParser() + ap.add_argument('--target', default='.') + ap.add_argument('--profile', choices=['coding','syntaro'], default='coding') + args=ap.parse_args() + root=Path(__file__).resolve().parents[1] + target=Path(args.target).resolve() + target.mkdir(parents=True, exist_ok=True) + + # Three owned skills only. + for name in ('planner','executor','verifier'): + src=root/'skills'/name + dst=target/'.agents'/'skills'/name + if dst.exists(): shutil.rmtree(dst) + shutil.copytree(src,dst) + + # Schemas and profile. + schema_dst=target/'.agent-stack'/'schemas'; schema_dst.mkdir(parents=True, exist_ok=True) + for p in (root/'schemas').glob('*.json'): shutil.copy2(p,schema_dst/p.name) + (target/'.agent-stack'/'profile').write_text(args.profile+'\n', encoding='utf-8') + + # Shared policy for Codex/OMP/other AGENTS readers. + merge_block(target/'AGENTS.md', (root/'templates'/'AGENTS.block.md').read_text(encoding='utf-8')) + + # OMP sticky rules; do not destroy existing rules. + omp_rules=target/'.omp'/'RULES.md'; omp_rules.parent.mkdir(parents=True, exist_ok=True) + sticky=(root/'templates'/'OMP_RULES.md').read_text(encoding='utf-8').strip() + existing=omp_rules.read_text(encoding='utf-8') if omp_rules.exists() else '' + marker='# Agent Stack — sticky OMP rules' + if marker not in existing: + omp_rules.write_text(existing.rstrip()+('\n\n' if existing.strip() else '')+sticky+'\n', encoding='utf-8') + + # Runtime helpers and ChatGPT Work instructions. + bindir=target/'.agent-stack'/'bin'; bindir.mkdir(parents=True, exist_ok=True) + for helper in ('select_profile.py','build_work_bundles.py','doctor.py'): + shutil.copy2(root/'scripts'/helper, bindir/helper) + work=target/'.agent-stack'/'chatgpt-work'; work.mkdir(parents=True, exist_ok=True) + shutil.copy2(root/'templates'/'WORK_PROJECT_INSTRUCTIONS.md', work/'PROJECT_INSTRUCTIONS.md') + print(f'Core installed in {target}') + print('Owned skills: planner, executor, verifier') + print(f'Profile: {args.profile}') + +if __name__=='__main__': main() diff --git a/.agents/skills/agent-stack-v5-minimal/scripts/select_profile.py b/.agents/skills/agent-stack-v5-minimal/scripts/select_profile.py new file mode 100644 index 0000000..00bbf5c --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/scripts/select_profile.py @@ -0,0 +1,5 @@ +#!/usr/bin/env python3 +import argparse +from pathlib import Path +p=argparse.ArgumentParser(); p.add_argument('profile', choices=['coding','syntaro']); p.add_argument('--target', default='.') +a=p.parse_args(); root=Path(a.target).resolve(); d=root/'.agent-stack'; d.mkdir(parents=True, exist_ok=True); (d/'profile').write_text(a.profile+'\n'); print(a.profile) diff --git a/.agents/skills/agent-stack-v5-minimal/skills/executor/SKILL.md b/.agents/skills/agent-stack-v5-minimal/skills/executor/SKILL.md new file mode 100644 index 0000000..a42293e --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/skills/executor/SKILL.md @@ -0,0 +1,86 @@ +--- +name: executor +description: Execute an approved coding plan with tight scope, root-cause-first failure handling, regression limits, and plan adherence. Designed to avoid patch loops and unnecessary rewrites. +--- + +# Executor + +Use this skill after a plan is approved. Optimize for a coherent implementation that reaches verification with as few corrective loops as possible. + +## Core rule + +Implement the plan; do not rediscover or redesign the task while coding. If material evidence contradicts the plan, stop and return `REPLAN` rather than improvising a new architecture inside the implementation loop. + +## Before editing + +1. Read the approved plan and acceptance criteria. +2. Confirm the current repo state still matches the plan. +3. Use Graphify for a scoped dependency/call-path check when useful. +4. For UI work, load the plan's UI contract and the installed UI UX Pro Max guidance. Preserve the incumbent design system. +5. Identify the smallest coherent set of files that should change. + +## Implementation behavior + +- Make changes in dependency order. +- Preserve existing APIs/contracts unless the plan explicitly changes them. +- Prefer existing abstractions and components over introducing parallel ones. +- Do not perform opportunistic refactors unrelated to the task. +- Do not widen scope to “clean up” neighboring code. +- Add or update tests that directly prove the planned behavior. +- For UI, implement states and responsive behavior specified by the UI contract, not just the happy-path screenshot. + +## Failure protocol — anti-hamster-wheel + +An unexpected failure is evidence, not an invitation to patch randomly. + +### First unexpected failure/regression + +Before another edit: +1. reproduce it; +2. classify whether it is caused by the current change, pre-existing, environment-related, or evidence that the plan is wrong; +3. trace the failure to a concrete cause using source/tests/runtime evidence; +4. make **one surgical fix** only if the cause is proven and local. + +If the cause cannot be proven local, return `REPLAN`. + +### Second unexpected regression + +Stop implementation. Do not stack another speculative patch. + +Return: +- what failed; +- evidence collected; +- which plan assumption appears wrong; +- files already changed; +- recommended replanning scope. + +Status: `REPLAN`. + +## Plan deviation rule + +Any material deviation — new service, new persistence model, changed API contract, changed product behavior, broad refactor, or new UI direction — requires replanning unless the plan explicitly allowed it. + +## Local verification during execution + +Run focused checks as you go, but do not substitute executor self-checks for independent verification. Typical checks: +- relevant unit/integration tests; +- typecheck/build; +- lint/static analysis where meaningful; +- targeted runtime reproduction; +- UI render/smoke check for UI changes. + +## Handoff report + +Return a concise implementation artifact containing: +- plan/requirement IDs implemented; +- changed files; +- tests/checks run and outcomes; +- deviations from plan (preferably none); +- unexpected failures encountered and their proven causes; +- known limitations; +- evidence the verifier should inspect. + +End with one of: +- `IMPLEMENTED_FOR_VERIFICATION`; +- `REPLAN`; +- `HUMAN_DECISION`. diff --git a/.agents/skills/agent-stack-v5-minimal/skills/planner/SKILL.md b/.agents/skills/agent-stack-v5-minimal/skills/planner/SKILL.md new file mode 100644 index 0000000..d3a6a1e --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/skills/planner/SKILL.md @@ -0,0 +1,110 @@ +--- +name: planner +description: Plan non-trivial coding work before edits. Grounds in the repository, uses architecture/UI capabilities when relevant, produces a bounded implementation and verification contract, and challenges its own assumptions before handing off. +--- + +# Planner + +Use this skill for any non-trivial change before editing source code. The goal is first-pass correctness, not token minimization. + +## Core rule + +Do not implement. Build enough evidence that the executor can make one coherent change without discovering basic architecture, requirements, or UI decisions halfway through implementation. + +## Capability order + +Use the installed upstream capabilities rather than re-implementing them here: + +1. **Graphify** for repository grounding, call paths, dependencies, and impact discovery. Prefer graph evidence before broad repetitive grep/search when a graph exists. +2. **Archify** when the change crosses boundaries, changes a runtime/data flow, or the architecture is unclear enough that a diagram/flow model reduces risk. +3. **UI UX Pro Max** for any user-facing UI/UX change. Use it before implementation to establish the design direction and constraints. +4. Existing repo evidence: source, tests, docs, ADRs, schemas, configs, issue context, and runtime behavior. + +If a capability is unavailable, fall back to direct repository inspection. Never invent its output. + +## Planning procedure + +### 1. Restate the requested outcome + +Define the user-visible or system-visible result in concrete terms. Separate requirements from implementation ideas. + +### 2. Ground in the repository + +Identify: +- entry points and relevant components; +- callers/callees and data/control flow; +- existing tests and behavioral contracts; +- persistence/schema/API boundaries; +- configuration and feature-flag dependencies; +- adjacent code that is likely to regress. + +For a large repo, query Graphify first, then read the relevant source. Grep/search is for confirmation and details, not for reconstructing the entire architecture from scratch. + +### 3. Build an impact map + +State what is expected to change and what must remain unchanged. If the change spans multiple services/modules or modifies an important flow, use Archify to make the impact explicit. + +### 4. Resolve UI direction before coding + +For UI work, invoke UI UX Pro Max and inspect the incumbent product language. Produce a compact UI contract that covers: +- hierarchy and information architecture; +- layout/density; +- typography and spacing; +- component/state behavior; +- responsive behavior; +- accessibility constraints; +- existing design tokens/components to reuse; +- anti-patterns to avoid. + +Do not let the executor invent a new visual language during implementation. + +### 5. Produce the plan contract + +The plan must contain: + +- **Goal** +- **Requirements** with stable IDs (`R1`, `R2`, ...) +- **Evidence consulted** +- **Affected components/files** +- **Invariants / must-not-change behavior** +- **Assumptions** and how each was validated +- **Architecture impact** +- **Implementation steps** in dependency order +- **Acceptance criteria** mapped to requirement IDs +- **Verification plan** with concrete commands/runtime evidence +- **Regression surface** +- **UI contract** when applicable +- **Open decisions / missing evidence** +- **Explicit non-goals** + +Keep the plan implementation-ready. Avoid generic steps such as “update backend” or “add tests.” + +### 6. Adversarial review before handoff + +Try to invalidate the plan: +- What existing behavior could this break? +- What dependency or call path might have been missed? +- Which assumption is weakest? +- Is the plan changing more architecture than the request requires? +- Is there a simpler implementation that preserves more existing behavior? +- Can every acceptance criterion actually be verified? + +Revise the plan before handing it off if the review exposes a gap. + +## Syntaro profile + +If `.agent-stack/profile` contains `syntaro`, be stricter: +- surface missing evidence instead of silently filling gaps; +- distinguish implementation questions from product/CTO decisions; +- include dependencies and verification evidence required before execution; +- do not mark a plan executable while a material decision remains unresolved; +- explicitly define when the executor must stop and return for replanning. + +## Handoff + +End with one of: +- `PLAN_READY` — bounded and executable; +- `NEEDS_EVIDENCE` — specify exactly what evidence is missing; +- `HUMAN_DECISION` — specify the decision and why it cannot safely be inferred. + +The executor receives the plan, not the planner's hidden reasoning. diff --git a/.agents/skills/agent-stack-v5-minimal/skills/verifier/SKILL.md b/.agents/skills/agent-stack-v5-minimal/skills/verifier/SKILL.md new file mode 100644 index 0000000..d1dd98f --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/skills/verifier/SKILL.md @@ -0,0 +1,107 @@ +--- +name: verifier +description: Independently verify a coding change against the plan, acceptance criteria, architecture, regressions, and rendered UI. Produces evidence-backed READY, FIX_LOCAL, REPLAN, or HUMAN_DECISION outcomes. +--- + +# Verifier + +Use this skill after implementation. Prefer a fresh context/agent when the harness supports it. Do not accept the executor's claims as proof. + +## Core rule + +Verification is requirement-by-requirement evidence collection, not a general code review and not “tests passed, therefore done.” + +By default, do not edit code. Diagnose and classify first. + +## Inputs + +Use: +- approved plan and acceptance criteria; +- implementation report; +- actual diff and current repository state; +- tests/build/runtime output; +- incumbent product/design context for UI work. + +## Verification procedure + +### 1. Re-ground independently + +Use Graphify/source inspection to confirm affected paths and dependencies rather than trusting the executor's file list. For architecture-sensitive changes, use Archify or equivalent source-backed flow inspection to verify the intended architecture delta. + +### 2. Verify every requirement + +For each requirement/acceptance criterion, record: +- `PASS`, `FAIL`, or `UNPROVEN`; +- concrete evidence: test, command output, code path, runtime behavior, screenshot/render, API result, or other reproducible proof. + +`UNPROVEN` is not `PASS`. + +### 3. Regression verification + +Check the regression surface from the plan plus any new surface revealed by the diff: +- callers and downstream consumers; +- API/schema compatibility; +- state/error/empty/loading paths; +- permissions/auth boundaries where relevant; +- existing tests around affected behavior; +- build/type integrity; +- unintended files/behaviors changed. + +### 4. Diff review + +Inspect for: +- changes outside the approved scope; +- duplicated abstractions or unnecessary indirection; +- hidden behavior changes; +- dead code or incomplete migrations; +- error handling that masks failures; +- tests that only mirror the implementation rather than prove behavior. + +### 5. UI verification + +For UI-facing changes, verification must include the **rendered result**, not source inspection alone. + +Use Impeccable for deterministic/visual design checks and critique. Verify at least: +- hierarchy and readability; +- layout/alignment/spacing; +- component consistency with the product; +- loading/empty/error/disabled/selected states as relevant; +- responsive behavior at relevant widths; +- obvious accessibility issues; +- whether the implementation respects the planner's UI contract. + +Use UI UX Pro Max as design reference; use Impeccable to inspect what was actually built. + +Do not enter a random CSS tweak loop. Name the observed defect and its likely cause before proposing a fix. + +## Outcome policy + +Return exactly one primary status: + +### `READY` +Every material acceptance criterion is proven and no blocking regression remains. + +### `FIX_LOCAL` +A narrow defect exists, its root cause is proven, the plan remains valid, and one bounded fix should resolve it. Specify the exact defect and re-verification required. + +### `REPLAN` +Use when: +- a material plan assumption is false; +- the change requires broader architecture/scope than planned; +- there is a second unexpected regression; +- repeated local fixes are accumulating; +- verification exposes missing requirements or contradictory acceptance criteria. + +### `HUMAN_DECISION` +A product/architecture/risk decision is genuinely required and cannot safely be inferred from repository evidence. + +## Syntaro profile + +If `.agent-stack/profile` contains `syntaro`, require stronger evidence: +- explicit requirement-to-evidence mapping; +- architecture compliance for changed flows; +- missing-evidence list; +- open decision list; +- verification readiness suitable for another human or agent to audit. + +Never convert uncertainty into a pass merely to complete the task. diff --git a/.agents/skills/agent-stack-v5-minimal/templates/AGENTS.block.md b/.agents/skills/agent-stack-v5-minimal/templates/AGENTS.block.md new file mode 100644 index 0000000..ce7b5af --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/templates/AGENTS.block.md @@ -0,0 +1,26 @@ + +## Coding control plane + +Optimize for **iterations-to-verified**, not token count. For non-trivial coding work, use the three role skills in order: + +1. `planner` — ground in the repo, define impact/acceptance/verification, and challenge the plan before edits. +2. `executor` — implement the approved plan without scope drift; root-cause unexpected failures before patching. +3. `verifier` — independently prove requirements, regressions, architecture, and rendered UI before declaring done. + +Use upstream capabilities instead of reimplementing them: +- **Graphify** for repository graph, call paths, dependencies, and impact discovery. +- **Archify** for architecture/runtime/data-flow modeling when boundaries or flows matter. +- **UI UX Pro Max** before UI implementation to establish design direction and constraints. +- **Impeccable** after UI implementation to inspect the rendered result and detect design problems. + +Hard rules: +- Do not skip verification for non-trivial changes. +- Do not optimize for fewer tokens or fewer reads; optimize for fewer wrong edits and fix loops. +- One unexpected regression: diagnose root cause before another edit. +- Two unexpected regressions: stop patching and return to planning. +- A material plan deviation requires replanning rather than silent improvisation. +- UI changes require a design contract before coding and rendered verification afterward. +- `READY` means evidence-backed acceptance criteria, not “the code looks fine.” + +Project profile is stored in `.agent-stack/profile` (`coding` or `syntaro`). The same three skills are used in both modes; `syntaro` makes planning and verification stricter. + diff --git a/.agents/skills/agent-stack-v5-minimal/templates/OMP_RULES.md b/.agents/skills/agent-stack-v5-minimal/templates/OMP_RULES.md new file mode 100644 index 0000000..6f5348a --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/templates/OMP_RULES.md @@ -0,0 +1,11 @@ +# Agent Stack — sticky OMP rules + +- Optimize for iterations-to-verified, not token count. +- For non-trivial changes: planner -> executor -> verifier. +- Prefer Graphify for large-repo grounding before broad repetitive grep/search. +- Use Archify when architecture/runtime/data flow is materially affected or unclear. +- For UI work: UI UX Pro Max before implementation; Impeccable on the rendered result after implementation. +- First unexpected regression: reproduce and prove root cause before another edit. +- Second unexpected regression: stop and replan. Do not stack speculative patches. +- Material deviation from the approved plan requires replanning. +- Do not claim completion without requirement-level evidence. diff --git a/.agents/skills/agent-stack-v5-minimal/templates/WORK_PROJECT_INSTRUCTIONS.md b/.agents/skills/agent-stack-v5-minimal/templates/WORK_PROJECT_INSTRUCTIONS.md new file mode 100644 index 0000000..f4d79a1 --- /dev/null +++ b/.agents/skills/agent-stack-v5-minimal/templates/WORK_PROJECT_INSTRUCTIONS.md @@ -0,0 +1,15 @@ +# Coding workflow for ChatGPT Work + +Use the installed/uploaded `planner`, `executor`, and `verifier` skills as the control plane for coding tasks. + +For non-trivial work, run the phases in order: PLAN -> EXECUTE -> VERIFY. Optimize for first-pass correctness and low fix-loop count, not token efficiency. + +When available, use: +- Graphify for repository structure, dependencies and call paths; +- Archify for architecture/runtime/data-flow analysis; +- UI UX Pro Max to define UI direction before implementation; +- Impeccable to inspect and critique the rendered UI after implementation. + +Never treat executor self-checks as independent verification. One unexpected regression requires root-cause analysis before another edit; a second unexpected regression invalidates the current plan and requires replanning. + +For Syntaro-oriented work, emphasize missing evidence, open decisions, architecture impact, requirement-to-evidence mapping, and independent verification readiness. diff --git a/.agents/skills/coding-control-plane/SKILL.md b/.agents/skills/coding-control-plane/SKILL.md new file mode 100644 index 0000000..d1c66b9 --- /dev/null +++ b/.agents/skills/coding-control-plane/SKILL.md @@ -0,0 +1,120 @@ +--- +name: coding-control-plane +description: Plan, execute, and independently verify non-trivial coding work with strong repository grounding, explicit acceptance criteria, anti-regression gates, and strict limits on fix loops. Use for coding tasks where first-pass correctness matters more than token cost. +--- + +# Coding Control Plane + +Use this workflow for non-trivial coding changes. Optimize for **few iterations to verified**, not for short prompts or low token usage. + +## Operating model + +Run three phases in order unless the user explicitly requests only one: + +1. **PLAN** — understand the repository and produce an implementation/verification contract. +2. **EXECUTE** — implement the approved plan without redesigning the task mid-loop. +3. **VERIFY** — independently prove each acceptance criterion and detect regressions. + +For small obvious edits, compress the phases, but keep the same discipline. + +## PLAN + +Before writing code: + +- Restate the desired observable outcome. +- Inspect the relevant repository paths, tests, schemas, configs, APIs, and runtime flow. +- Prefer structural evidence (symbol/call/dependency graph, architecture docs, code navigation) before broad repetitive grep/search when available. +- Identify affected components and adjacent regression surfaces. +- State invariants: behavior that must not change. +- Record assumptions and the evidence that validates them. +- For UI work, invoke the installed UI/UX skill before implementation and produce a UI contract. +- For architecture-sensitive work, make the before/after flow explicit. + +Produce: + +- Goal +- Requirements `R1`, `R2`, ... +- Evidence consulted +- Affected components/files +- Invariants / must-not-change behavior +- Assumptions and validation +- Architecture impact +- Implementation steps in dependency order +- Acceptance criteria mapped to requirements +- Verification plan with concrete evidence/commands +- Regression surface +- UI contract when relevant +- Open decisions / missing evidence +- Non-goals + +Then challenge the plan: what dependency, assumption, behavior, or simpler implementation might have been missed? Revise before execution. + +End planning with `PLAN_READY`, `NEEDS_EVIDENCE`, or `HUMAN_DECISION`. + +## EXECUTE + +Implement the plan, not a new design discovered while coding. + +Before edits, confirm the current repo still matches the plan. Change the smallest coherent file set. Reuse existing components, APIs, and abstractions. Avoid opportunistic refactors. + +For UI work, follow the UI contract and the existing product language. Implement real states: loading, empty, error, disabled, selected, responsive behavior where relevant. + +### Anti-hamster-wheel protocol + +An unexpected failure is evidence, not permission to patch randomly. + +**First unexpected failure/regression:** +- reproduce it; +- classify it as current-change, pre-existing, environment, or plan-invalidating; +- trace it to a concrete cause; +- make one surgical fix only when the cause is proven local. + +If the cause is not proven local, stop and return `REPLAN`. + +**Second unexpected regression:** stop implementation. Do not stack another speculative patch. Return the evidence and the plan assumption that appears wrong. Status: `REPLAN`. + +Any material deviation — new service, persistence model, API contract, broad refactor, or new UI direction — requires replanning. + +End execution with `IMPLEMENTED_FOR_VERIFICATION`, `REPLAN`, or `HUMAN_DECISION`. + +## VERIFY + +Prefer a fresh context when possible. Do not treat executor claims as proof. + +For every requirement / acceptance criterion record `PASS`, `FAIL`, or `UNPROVEN` and attach reproducible evidence: tests, commands, code path, runtime behavior, API result, screenshot/render, or other proof. `UNPROVEN` is not `PASS`. + +Verify: + +- planned behavior; +- callers/downstream consumers; +- API/schema compatibility; +- loading/error/empty/state transitions; +- auth/permissions when relevant; +- build/type/test integrity; +- unintended files or behaviors changed; +- architecture delta; +- rendered UI for UI-facing changes. + +For UI, invoke the UI review skill and inspect the actual rendered result. Name each observed defect before proposing a fix. Do not enter random CSS tweaking. + +Return exactly one status: + +- `READY` — every material criterion is proven and no blocking regression remains. +- `FIX_LOCAL` — one narrow, proven defect; specify the exact fix and re-verification. +- `REPLAN` — false plan assumption, broader scope required, repeated regression, or missing/contradictory requirements. +- `HUMAN_DECISION` — a genuine product/architecture/risk decision is unresolved. + +## Syntaro mode + +When the task is for Syntaro planning/verification, make PLAN and VERIFY stricter: + +- distinguish implementation questions from CTO/product decisions; +- surface missing evidence rather than filling gaps silently; +- require explicit requirement-to-evidence mapping; +- require architecture compliance for changed flows; +- treat the executor as replaceable; the plan and verification artifacts are the stable contract; +- never mark work ready while a material decision or evidence gap remains. + +## Output templates + +Use `assets/plan-template.md` for planning handoff and `assets/verification-template.md` for the final verification report when helpful. diff --git a/.agents/skills/coding-control-plane/agents/openai.yaml b/.agents/skills/coding-control-plane/agents/openai.yaml new file mode 100644 index 0000000..44ad6e7 --- /dev/null +++ b/.agents/skills/coding-control-plane/agents/openai.yaml @@ -0,0 +1,15 @@ +interface: + display_name: coding control plane + short_description: Plan, execute, and independently verify non-trivial coding work + with strong repository grounding, explicit acceptance criteria, anti-regression + gates, and strict limits on fix loops. Use for coding tasks where first-pass correctness + matters more than token cost. + icon_small: assets/icon.svg + icon_large: assets/icon.svg +policy: + products: + - chatgpt + - codex + - api + - atlas + allow_implicit_invocation: true diff --git a/.agents/skills/coding-control-plane/assets/icon.svg b/.agents/skills/coding-control-plane/assets/icon.svg new file mode 100644 index 0000000..c782ded --- /dev/null +++ b/.agents/skills/coding-control-plane/assets/icon.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/.agents/skills/coding-control-plane/assets/plan-template.md b/.agents/skills/coding-control-plane/assets/plan-template.md new file mode 100644 index 0000000..998c5f5 --- /dev/null +++ b/.agents/skills/coding-control-plane/assets/plan-template.md @@ -0,0 +1,34 @@ +# Plan + +## Goal + +## Requirements +- R1 — + +## Evidence consulted + +## Affected components/files + +## Invariants / must not change + +## Assumptions + validation + +## Architecture impact + +## Implementation steps +1. + +## Acceptance criteria +- R1 / AC1 — + +## Verification plan + +## Regression surface + +## UI contract (if applicable) + +## Open decisions / missing evidence + +## Non-goals + +**Status:** PLAN_READY | NEEDS_EVIDENCE | HUMAN_DECISION diff --git a/.agents/skills/coding-control-plane/assets/verification-template.md b/.agents/skills/coding-control-plane/assets/verification-template.md new file mode 100644 index 0000000..2e15499 --- /dev/null +++ b/.agents/skills/coding-control-plane/assets/verification-template.md @@ -0,0 +1,20 @@ +# Verification + +## Requirement evidence +| Requirement | Status | Evidence | +|---|---|---| +| R1 | PASS / FAIL / UNPROVEN | | + +## Regression checks + +## Architecture compliance + +## UI/render evidence + +## Unexpected changes + +## Missing evidence + +## Required next action + +**Status:** READY | FIX_LOCAL | REPLAN | HUMAN_DECISION diff --git a/.agents/skills/coding-control-plane/references/anti-loop-rules.md b/.agents/skills/coding-control-plane/references/anti-loop-rules.md new file mode 100644 index 0000000..b2024c6 --- /dev/null +++ b/.agents/skills/coding-control-plane/references/anti-loop-rules.md @@ -0,0 +1,13 @@ +# Anti-loop rules + +Use these as hard gates when an implementation begins to thrash. + +- Reading/analysis can be extensive. Writing should be deliberate. +- A failing test does not automatically justify an edit. +- Diagnose before changing code. +- One proven local cause permits one surgical fix. +- A second unexpected regression invalidates the current execution path: stop and replan. +- Repeated CSS tweaks without a named rendered defect are prohibited. +- Repeated edits outside the planned file set require a fresh impact analysis. +- “Tests pass” is not equivalent to “requirement proven.” +- Verification should be independent from implementation when the harness permits it. diff --git a/.agents/skills/executor/SKILL.md b/.agents/skills/executor/SKILL.md new file mode 100644 index 0000000..a42293e --- /dev/null +++ b/.agents/skills/executor/SKILL.md @@ -0,0 +1,86 @@ +--- +name: executor +description: Execute an approved coding plan with tight scope, root-cause-first failure handling, regression limits, and plan adherence. Designed to avoid patch loops and unnecessary rewrites. +--- + +# Executor + +Use this skill after a plan is approved. Optimize for a coherent implementation that reaches verification with as few corrective loops as possible. + +## Core rule + +Implement the plan; do not rediscover or redesign the task while coding. If material evidence contradicts the plan, stop and return `REPLAN` rather than improvising a new architecture inside the implementation loop. + +## Before editing + +1. Read the approved plan and acceptance criteria. +2. Confirm the current repo state still matches the plan. +3. Use Graphify for a scoped dependency/call-path check when useful. +4. For UI work, load the plan's UI contract and the installed UI UX Pro Max guidance. Preserve the incumbent design system. +5. Identify the smallest coherent set of files that should change. + +## Implementation behavior + +- Make changes in dependency order. +- Preserve existing APIs/contracts unless the plan explicitly changes them. +- Prefer existing abstractions and components over introducing parallel ones. +- Do not perform opportunistic refactors unrelated to the task. +- Do not widen scope to “clean up” neighboring code. +- Add or update tests that directly prove the planned behavior. +- For UI, implement states and responsive behavior specified by the UI contract, not just the happy-path screenshot. + +## Failure protocol — anti-hamster-wheel + +An unexpected failure is evidence, not an invitation to patch randomly. + +### First unexpected failure/regression + +Before another edit: +1. reproduce it; +2. classify whether it is caused by the current change, pre-existing, environment-related, or evidence that the plan is wrong; +3. trace the failure to a concrete cause using source/tests/runtime evidence; +4. make **one surgical fix** only if the cause is proven and local. + +If the cause cannot be proven local, return `REPLAN`. + +### Second unexpected regression + +Stop implementation. Do not stack another speculative patch. + +Return: +- what failed; +- evidence collected; +- which plan assumption appears wrong; +- files already changed; +- recommended replanning scope. + +Status: `REPLAN`. + +## Plan deviation rule + +Any material deviation — new service, new persistence model, changed API contract, changed product behavior, broad refactor, or new UI direction — requires replanning unless the plan explicitly allowed it. + +## Local verification during execution + +Run focused checks as you go, but do not substitute executor self-checks for independent verification. Typical checks: +- relevant unit/integration tests; +- typecheck/build; +- lint/static analysis where meaningful; +- targeted runtime reproduction; +- UI render/smoke check for UI changes. + +## Handoff report + +Return a concise implementation artifact containing: +- plan/requirement IDs implemented; +- changed files; +- tests/checks run and outcomes; +- deviations from plan (preferably none); +- unexpected failures encountered and their proven causes; +- known limitations; +- evidence the verifier should inspect. + +End with one of: +- `IMPLEMENTED_FOR_VERIFICATION`; +- `REPLAN`; +- `HUMAN_DECISION`. diff --git a/.agents/skills/planner/SKILL.md b/.agents/skills/planner/SKILL.md new file mode 100644 index 0000000..d3a6a1e --- /dev/null +++ b/.agents/skills/planner/SKILL.md @@ -0,0 +1,110 @@ +--- +name: planner +description: Plan non-trivial coding work before edits. Grounds in the repository, uses architecture/UI capabilities when relevant, produces a bounded implementation and verification contract, and challenges its own assumptions before handing off. +--- + +# Planner + +Use this skill for any non-trivial change before editing source code. The goal is first-pass correctness, not token minimization. + +## Core rule + +Do not implement. Build enough evidence that the executor can make one coherent change without discovering basic architecture, requirements, or UI decisions halfway through implementation. + +## Capability order + +Use the installed upstream capabilities rather than re-implementing them here: + +1. **Graphify** for repository grounding, call paths, dependencies, and impact discovery. Prefer graph evidence before broad repetitive grep/search when a graph exists. +2. **Archify** when the change crosses boundaries, changes a runtime/data flow, or the architecture is unclear enough that a diagram/flow model reduces risk. +3. **UI UX Pro Max** for any user-facing UI/UX change. Use it before implementation to establish the design direction and constraints. +4. Existing repo evidence: source, tests, docs, ADRs, schemas, configs, issue context, and runtime behavior. + +If a capability is unavailable, fall back to direct repository inspection. Never invent its output. + +## Planning procedure + +### 1. Restate the requested outcome + +Define the user-visible or system-visible result in concrete terms. Separate requirements from implementation ideas. + +### 2. Ground in the repository + +Identify: +- entry points and relevant components; +- callers/callees and data/control flow; +- existing tests and behavioral contracts; +- persistence/schema/API boundaries; +- configuration and feature-flag dependencies; +- adjacent code that is likely to regress. + +For a large repo, query Graphify first, then read the relevant source. Grep/search is for confirmation and details, not for reconstructing the entire architecture from scratch. + +### 3. Build an impact map + +State what is expected to change and what must remain unchanged. If the change spans multiple services/modules or modifies an important flow, use Archify to make the impact explicit. + +### 4. Resolve UI direction before coding + +For UI work, invoke UI UX Pro Max and inspect the incumbent product language. Produce a compact UI contract that covers: +- hierarchy and information architecture; +- layout/density; +- typography and spacing; +- component/state behavior; +- responsive behavior; +- accessibility constraints; +- existing design tokens/components to reuse; +- anti-patterns to avoid. + +Do not let the executor invent a new visual language during implementation. + +### 5. Produce the plan contract + +The plan must contain: + +- **Goal** +- **Requirements** with stable IDs (`R1`, `R2`, ...) +- **Evidence consulted** +- **Affected components/files** +- **Invariants / must-not-change behavior** +- **Assumptions** and how each was validated +- **Architecture impact** +- **Implementation steps** in dependency order +- **Acceptance criteria** mapped to requirement IDs +- **Verification plan** with concrete commands/runtime evidence +- **Regression surface** +- **UI contract** when applicable +- **Open decisions / missing evidence** +- **Explicit non-goals** + +Keep the plan implementation-ready. Avoid generic steps such as “update backend” or “add tests.” + +### 6. Adversarial review before handoff + +Try to invalidate the plan: +- What existing behavior could this break? +- What dependency or call path might have been missed? +- Which assumption is weakest? +- Is the plan changing more architecture than the request requires? +- Is there a simpler implementation that preserves more existing behavior? +- Can every acceptance criterion actually be verified? + +Revise the plan before handing it off if the review exposes a gap. + +## Syntaro profile + +If `.agent-stack/profile` contains `syntaro`, be stricter: +- surface missing evidence instead of silently filling gaps; +- distinguish implementation questions from product/CTO decisions; +- include dependencies and verification evidence required before execution; +- do not mark a plan executable while a material decision remains unresolved; +- explicitly define when the executor must stop and return for replanning. + +## Handoff + +End with one of: +- `PLAN_READY` — bounded and executable; +- `NEEDS_EVIDENCE` — specify exactly what evidence is missing; +- `HUMAN_DECISION` — specify the decision and why it cannot safely be inferred. + +The executor receives the plan, not the planner's hidden reasoning. diff --git a/.agents/skills/ui-ux-curated-full/MANIFEST.md b/.agents/skills/ui-ux-curated-full/MANIFEST.md new file mode 100644 index 0000000..a644297 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/MANIFEST.md @@ -0,0 +1,49 @@ +# Included files + +- `SKILL.md` +- `checklists/pre-delivery.md` +- `checklists/pre-implementation.md` +- `checklists/screenshot-review.md` +- `presets/dark-glass.json` +- `presets/glass-neutral.json` +- `presets/liquid-blue.json` +- `presets/liquid-warm.json` +- `references/accessibility.md` +- `references/anti-generic-ai-ui.md` +- `references/chat-assistant.md` +- `references/color-and-contrast.md` +- `references/dashboards.md` +- `references/density-and-spacing.md` +- `references/interaction-and-motion.md` +- `references/mobile-first.md` +- `references/nuxt-vue-tailwind.md` +- `references/planning-verification.md` +- `references/product-ui-patterns.md` +- `references/responsive.md` +- `references/typography.md` +- `references/ux-foundations.md` +- `snippets/glass.css` +- `snippets/liquid-glass.css` +- `snippets/liquid-morph.css` +- `snippets/tailwind-patterns.md` +- `snippets/tokens.css` +- `styles/glassmorphism-dashboard.md` +- `styles/glassmorphism.md` +- `styles/liquid-glass-mobile.md` +- `styles/liquid-glass.md` +- `styles/liquid-morph-assistant.md` +- `styles/liquid-morph.md` +- `templates/assistant-panel.md` +- `templates/command-palette.md` +- `templates/dashboard-shell.md` +- `templates/design-system-master.md` +- `templates/detail-drawer.md` +- `templates/empty-state.md` +- `templates/form-flow.md` +- `templates/mobile-bottom-sheet.md` +- `templates/page-override.md` +- `templates/planner-screen.md` +- `templates/settings-page.md` +- `templates/table-toolbar.md` +- `templates/ui-contract.md` +- `templates/verifier-screen.md` diff --git a/.agents/skills/ui-ux-curated-full/SKILL.md b/.agents/skills/ui-ux-curated-full/SKILL.md new file mode 100644 index 0000000..02c9154 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/SKILL.md @@ -0,0 +1,39 @@ +--- +name: ui-ux-curated-full +description: High-quality product UI/UX design system for web and mobile with curated glassmorphism, liquid glass, and liquid morph patterns. Use before implementing UI, when redesigning a surface, or when reviewing interfaces that feel generic, inconsistent, dense, or visually weak. Produces a stable UI contract and page-level design decisions before code. +--- +# UI/UX Curated Full + +Use this skill as the design-intelligence layer before implementation. Do not jump directly from a vague request to CSS. First understand the existing product, define the information hierarchy, pick a restrained visual direction, and create a UI contract. + +## Required workflow +1. Read the existing product language and reuse existing components/tokens whenever reasonable. +2. Read `references/ux-foundations.md` and the most relevant product-pattern reference. +3. For a new or materially redesigned surface, choose at most one primary style family from `styles/`. +4. Fill `templates/ui-contract.md` before implementation. For multi-page work, also create `templates/design-system-master.md` plus page overrides. +5. Use the closest page/component templates as structure, not as pixel-perfect output. +6. Implement with semantic tokens and explicit states. +7. Review the rendered result with the separate visual-verifier skill. Fix observed defects, not imagined ones. + +## Style policy +- Default product surfaces are solid, legible, and task-first. +- Glass is an elevation/hierarchy material, not wallpaper. +- Liquid effects belong on focal, floating, transient, or assistant surfaces; data tables and long-form forms stay calmer. +- Never mix glassmorphism, liquid glass, and liquid morph on one screen unless one is clearly dominant and the others are limited to tiny accents. + +## Load only what is relevant +- General UX: `references/ux-foundations.md` +- Accessibility: `references/accessibility.md` +- Mobile: `references/mobile-first.md` +- Dashboards: `references/dashboards.md` +- Assistant/chat: `references/chat-assistant.md` +- Planning/verification tools: `references/planning-verification.md` +- Vue/Nuxt/Tailwind: `references/nuxt-vue-tailwind.md` +- Visual style: one file from `styles/` +- Page/component pattern: one or two files from `templates/` + +## Non-negotiable anti-patterns +Do not ship generic AI-SaaS styling: purple/pink gradient as identity by default, glow everywhere, excessive pills, every section in a floating card, unreadable translucent tables, random radii/shadows, giant marketing typography inside productivity screens, decorative icons without meaning, or motion that delays task completion. + +## Output contract +Before coding, state: hierarchy, primary action, layout regions, density, type scale, semantic colors, surface/elevation rules, component states, responsive behavior, accessibility constraints, chosen style family, reusable existing components, and explicit anti-patterns. Use `templates/ui-contract.md`. diff --git a/.agents/skills/ui-ux-curated-full/agents/openai.yaml b/.agents/skills/ui-ux-curated-full/agents/openai.yaml new file mode 100644 index 0000000..a07973e --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/agents/openai.yaml @@ -0,0 +1,16 @@ +interface: + display_name: ui ux curated full + short_description: High-quality product UI/UX design system for web and mobile with + curated glassmorphism, liquid glass, and liquid morph patterns. Use before implementing + UI, when redesigning a surface, or when reviewing interfaces that feel generic, + inconsistent, dense, or visually weak. Produces a stable UI contract and page-level + design decisions before code. + icon_small: assets/icon.svg + icon_large: assets/icon.svg +policy: + products: + - chatgpt + - codex + - api + - atlas + allow_implicit_invocation: true diff --git a/.agents/skills/ui-ux-curated-full/assets/icon.svg b/.agents/skills/ui-ux-curated-full/assets/icon.svg new file mode 100644 index 0000000..4c3163a --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/assets/icon.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/.agents/skills/ui-ux-curated-full/checklists/pre-delivery.md b/.agents/skills/ui-ux-curated-full/checklists/pre-delivery.md new file mode 100644 index 0000000..3377aa3 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/checklists/pre-delivery.md @@ -0,0 +1,11 @@ +# Pre-Delivery Checklist +- 375 / 768 / 1024 / 1440 widths checked where relevant +- Keyboard/focus path works +- Contrast and icon labels checked +- Loading, empty, error, disabled, success states rendered +- Long text/IDs/localization do not break layout +- No unnecessary horizontal scroll +- Motion respects reduced-motion and never blocks action +- Glass transparency preserves readability +- No random one-off colors/radii/shadows +- Primary action remains obvious diff --git a/.agents/skills/ui-ux-curated-full/checklists/pre-implementation.md b/.agents/skills/ui-ux-curated-full/checklists/pre-implementation.md new file mode 100644 index 0000000..88b6100 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/checklists/pre-implementation.md @@ -0,0 +1,10 @@ +# Pre-Implementation Checklist +- Existing design language inspected +- UI contract completed +- Primary task/action unambiguous +- Correct information pattern chosen (table/list/cards/split view) +- Mobile transformation decided +- Empty/loading/error states specified +- Accessibility constraints specified +- One style family selected and bounded +- Existing components/tokens identified for reuse diff --git a/.agents/skills/ui-ux-curated-full/checklists/screenshot-review.md b/.agents/skills/ui-ux-curated-full/checklists/screenshot-review.md new file mode 100644 index 0000000..75d64da --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/checklists/screenshot-review.md @@ -0,0 +1,2 @@ +# Screenshot Review Checklist +Review the rendered UI in this order: hierarchy → layout/alignment → density → typography → contrast → component consistency → state clarity → responsive issues → decorative polish. Classify each issue before changing code. Prefer one targeted change per verified defect cluster. diff --git a/.agents/skills/ui-ux-curated-full/presets/dark-glass.json b/.agents/skills/ui-ux-curated-full/presets/dark-glass.json new file mode 100644 index 0000000..214f496 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/presets/dark-glass.json @@ -0,0 +1,13 @@ +{ + "name": "dark-glass", + "canvas": "near-black-solid", + "glass": "charcoal-translucent", + "border": "low-chroma-highlight", + "accent": "single-semantic-accent", + "text": "high-contrast", + "avoid": [ + "neon-everywhere", + "gray-on-gray", + "blur-behind-small-text" + ] +} diff --git a/.agents/skills/ui-ux-curated-full/presets/glass-neutral.json b/.agents/skills/ui-ux-curated-full/presets/glass-neutral.json new file mode 100644 index 0000000..2a9d663 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/presets/glass-neutral.json @@ -0,0 +1,18 @@ +{ + "name": "glass-neutral", + "canvas": "solid-neutral", + "glass_usage": [ + "header", + "floating-assistant", + "command-palette", + "modal" + ], + "blur": "moderate", + "border": "subtle", + "shadow": "soft", + "avoid": [ + "transparent-tables", + "nested-glass-cards", + "low-contrast-text" + ] +} diff --git a/.agents/skills/ui-ux-curated-full/presets/liquid-blue.json b/.agents/skills/ui-ux-curated-full/presets/liquid-blue.json new file mode 100644 index 0000000..96e5288 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/presets/liquid-blue.json @@ -0,0 +1,16 @@ +{ + "name": "liquid-blue", + "material": "liquid-glass", + "mood": "cool-technical", + "use": [ + "floating-navigation", + "assistant-shell", + "tool-overlay" + ], + "content_surface": "opaque", + "motion": "spatial-continuity", + "avoid": [ + "full-page-translucency", + "constant-morphing" + ] +} diff --git a/.agents/skills/ui-ux-curated-full/presets/liquid-warm.json b/.agents/skills/ui-ux-curated-full/presets/liquid-warm.json new file mode 100644 index 0000000..1989f59 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/presets/liquid-warm.json @@ -0,0 +1,15 @@ +{ + "name": "liquid-warm", + "material": "liquid-glass", + "mood": "friendly-premium", + "use": [ + "mobile-controls", + "onboarding-focal-surface", + "assistant" + ], + "content_surface": "warm-opaque", + "motion": "subtle", + "avoid": [ + "dense-data-on-glass" + ] +} diff --git a/.agents/skills/ui-ux-curated-full/references/accessibility.md b/.agents/skills/ui-ux-curated-full/references/accessibility.md new file mode 100644 index 0000000..58b7c82 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/accessibility.md @@ -0,0 +1,5 @@ +# Accessibility + +Target WCAG AA behavior. Body text and essential iconography need sufficient contrast. All functionality must be keyboard reachable with a visible focus indicator. Interactive icon-only controls require accessible names. Do not encode state or severity only by color. + +Forms need persistent labels, clear field-level errors, a programmatic relationship between errors and inputs, and sensible focus after submit. Dialogs trap focus while open and return focus to the invoking control. Respect reduced-motion preferences and browser zoom/text scaling. Touch targets should generally be at least ~44px where mobile/touch use is expected. diff --git a/.agents/skills/ui-ux-curated-full/references/anti-generic-ai-ui.md b/.agents/skills/ui-ux-curated-full/references/anti-generic-ai-ui.md new file mode 100644 index 0000000..b519790 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/anti-generic-ai-ui.md @@ -0,0 +1,5 @@ +# Anti-Generic AI UI + +Avoid: default purple-to-pink gradients, glowing borders everywhere, excessive glass cards, rounded pills for every control, giant centered copy in operational screens, meaningless sparkle icons, vague labels like “Magic”, uniform card grids regardless of information type, and animated blobs behind text. + +Prefer: product-specific hierarchy, grounded data density, clear status language, distinctive but restrained typography, purposeful asymmetry, and one memorable visual motif rather than ten effects. diff --git a/.agents/skills/ui-ux-curated-full/references/chat-assistant.md b/.agents/skills/ui-ux-curated-full/references/chat-assistant.md new file mode 100644 index 0000000..4037ee5 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/chat-assistant.md @@ -0,0 +1,5 @@ +# Assistant / Chat UI + +Chat should be an intent surface, not the entire product. Keep conversation compact and augment it with structured artifacts: plans, diffs, evidence, approvals, status, and suggested next actions. Distinguish user input, agent action, tool evidence, and system status visually. + +Use inline contextual actions near the relevant message/artifact. Avoid long assistant monologues when a compact card or delta view communicates state better. Mobile: prioritize composer, current task state, and one contextual panel at a time. diff --git a/.agents/skills/ui-ux-curated-full/references/color-and-contrast.md b/.agents/skills/ui-ux-curated-full/references/color-and-contrast.md new file mode 100644 index 0000000..31ff984 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/color-and-contrast.md @@ -0,0 +1,5 @@ +# Color and Contrast + +Build semantic tokens first: background, surface, elevated surface, text, muted text, border, primary, success, warning, danger, info, focus. Components consume semantic roles, not raw hex values. + +Keep most productivity surfaces neutral. Reserve saturated color for actions, status, and focus. Glass layers need stronger contrast discipline because blur/transparency lowers effective contrast. Dark mode requires independent token choices, not color inversion. diff --git a/.agents/skills/ui-ux-curated-full/references/dashboards.md b/.agents/skills/ui-ux-curated-full/references/dashboards.md new file mode 100644 index 0000000..8086dd2 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/dashboards.md @@ -0,0 +1,5 @@ +# Dashboard Patterns + +Lead with current state and exceptions, not vanity metrics. Put actionable blockers/alerts above historical summaries. Metrics need context (period, comparison, unit) and should not dominate if the user primarily needs to act. + +Use persistent filters when they change the whole surface, local filters near the region they affect, and visible filter state. Dense tables can use sticky headers, compact rows, column prioritization, and row-level actions revealed on focus/hover without hiding essential actions from touch users. diff --git a/.agents/skills/ui-ux-curated-full/references/density-and-spacing.md b/.agents/skills/ui-ux-curated-full/references/density-and-spacing.md new file mode 100644 index 0000000..72a684d --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/density-and-spacing.md @@ -0,0 +1,5 @@ +# Density and Spacing + +Use one density mode per surface. Dense dashboards may use 8/12/16px rhythm; standard product screens 8/16/24/32; marketing can be more spacious. Do not mix arbitrary gaps such as 13/19/27px without a system. + +Dense does not mean cramped: keep hit targets usable, separate unrelated actions, and reserve whitespace around decision points. Repeated list/table rows should be compact; forms and destructive confirmations deserve more breathing room. diff --git a/.agents/skills/ui-ux-curated-full/references/interaction-and-motion.md b/.agents/skills/ui-ux-curated-full/references/interaction-and-motion.md new file mode 100644 index 0000000..67fb78e --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/interaction-and-motion.md @@ -0,0 +1,5 @@ +# Interaction and Motion + +Motion communicates continuity, hierarchy, and state; it is not decoration. Prefer transform/opacity animations. Keep common UI transitions quick and cancellable. Enter can be slightly slower than exit. Avoid springy motion on serious error/destructive states. + +Use spatial continuity for drawers, sheets, assistants, and command surfaces. When a region expands, preserve the user's anchor. Never make the user wait for an animation before acting. Respect `prefers-reduced-motion`. diff --git a/.agents/skills/ui-ux-curated-full/references/mobile-first.md b/.agents/skills/ui-ux-curated-full/references/mobile-first.md new file mode 100644 index 0000000..960600a --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/mobile-first.md @@ -0,0 +1,5 @@ +# Mobile-first Product UX + +On mobile, one task per viewport. Use bottom sheets for contextual detail/actions, sticky primary actions when appropriate, and bottom navigation only for top-level destinations. Avoid desktop sidebars collapsed into tiny icon rails if the information model does not fit. + +Keep the most important status and next action above the fold. Forms should use appropriate input modes and autofill. Modals should usually become full-height sheets/pages on small screens. Support safe areas and one-handed reach for frequent actions. diff --git a/.agents/skills/ui-ux-curated-full/references/nuxt-vue-tailwind.md b/.agents/skills/ui-ux-curated-full/references/nuxt-vue-tailwind.md new file mode 100644 index 0000000..9fd481b --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/nuxt-vue-tailwind.md @@ -0,0 +1,5 @@ +# Nuxt / Vue / Tailwind Guidance + +Keep design tokens in CSS variables/Tailwind theme and components semantic. Do not scatter raw colors, shadows, or radii through templates. Prefer composable primitives for Button, Input, Select, Dialog/Sheet, Tooltip, Badge, Table/List row, and Surface. + +In Vue, keep visual variants explicit and bounded; avoid components with dozens of boolean props. Use slots for structured extension. For Nuxt, preserve SSR-safe behavior and avoid layout shifts from client-only measurement. Use responsive utilities to change information architecture, not merely font size. diff --git a/.agents/skills/ui-ux-curated-full/references/planning-verification.md b/.agents/skills/ui-ux-curated-full/references/planning-verification.md new file mode 100644 index 0000000..64658f9 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/planning-verification.md @@ -0,0 +1,5 @@ +# Planning and Verification UI + +Planning views should make assumptions, missing evidence, dependencies, acceptance criteria, and open decisions visible. Verification views should map each criterion to evidence and a pass/fail/unknown state. Unknown is not pass. + +Use progressive disclosure for raw logs. Show the smallest evidence needed to trust the verdict, with an explicit path to inspect source detail. Highlight plan deviations and unexpected changed files/components. Keep READY / FIX LOCAL / REPLAN / HUMAN DECISION visually distinct. diff --git a/.agents/skills/ui-ux-curated-full/references/product-ui-patterns.md b/.agents/skills/ui-ux-curated-full/references/product-ui-patterns.md new file mode 100644 index 0000000..ca68e76 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/product-ui-patterns.md @@ -0,0 +1,5 @@ +# Product UI Patterns + +For productivity/developer tools, organize screens around decisions and current state rather than feature categories. Put status, blockers, next action, and evidence near each other. Prefer a stable shell with context panels/drawers to page-hopping. + +Use cards only for independently scannable units. Use tables for comparison across many rows/columns, lists for narrative/heterogeneous items, and split panes when users repeatedly compare detail against a collection. Provide empty/loading/error states as designed states, not afterthoughts. diff --git a/.agents/skills/ui-ux-curated-full/references/responsive.md b/.agents/skills/ui-ux-curated-full/references/responsive.md new file mode 100644 index 0000000..3f09d4b --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/responsive.md @@ -0,0 +1,5 @@ +# Responsive Layout + +Design from the narrowest meaningful state upward. Decide what collapses, wraps, scrolls, becomes a drawer/sheet, or disappears. Do not merely shrink desktop UI. + +For work apps: on small screens keep the primary task, current status, and next action visible; move secondary metadata/actions behind a detail sheet or overflow menu. Tables should become priority-column lists/cards rather than horizontal-scroll prisons when practical. Test 375, 768, 1024, and 1440px widths plus long text and localization. diff --git a/.agents/skills/ui-ux-curated-full/references/typography.md b/.agents/skills/ui-ux-curated-full/references/typography.md new file mode 100644 index 0000000..8dcb9ef --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/typography.md @@ -0,0 +1,5 @@ +# Typography + +Use a restrained hierarchy: display/hero only where marketing or onboarding genuinely needs it; work apps typically need page title, section title, body, label, metadata/code. Keep body text around 14–16px depending on density, with comfortable line-height. Long-form text should not span the full viewport. + +Use tabular numerals for changing metrics and aligned numbers. Use monospace only for code, IDs, logs, and technical values. Avoid ultra-light text on translucent surfaces. diff --git a/.agents/skills/ui-ux-curated-full/references/ux-foundations.md b/.agents/skills/ui-ux-curated-full/references/ux-foundations.md new file mode 100644 index 0000000..d0f90df --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/references/ux-foundations.md @@ -0,0 +1,7 @@ +# UX Foundations + +Prioritize task completion over decoration. A screen needs one obvious primary purpose, one dominant action, and a stable visual hierarchy. Group by user intent rather than backend entities. Keep related controls near the content they affect. Prefer progressive disclosure over exposing every option at once. + +Use a small spacing scale consistently. Dense work surfaces can be compact, but interactive controls still need comfortable targets. Preserve alignment across sibling panels. Avoid unnecessary card nesting; whitespace, dividers, background changes, and typography often provide enough grouping. + +Every async action needs an immediate state: idle, hover/focus, pending, success, error, disabled where applicable. Preserve user input through recoverable errors. Destructive actions need clear consequence language and an undo path when feasible. diff --git a/.agents/skills/ui-ux-curated-full/snippets/glass.css b/.agents/skills/ui-ux-curated-full/snippets/glass.css new file mode 100644 index 0000000..444039e --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/snippets/glass.css @@ -0,0 +1,10 @@ +.glass-surface { + background: color-mix(in srgb, Canvas 76%, transparent); + border: 1px solid color-mix(in srgb, CanvasText 12%, transparent); + backdrop-filter: blur(18px) saturate(120%); + -webkit-backdrop-filter: blur(18px) saturate(120%); + box-shadow: 0 12px 32px color-mix(in srgb, CanvasText 10%, transparent); +} +@media (prefers-reduced-transparency: reduce) { + .glass-surface { background: Canvas; backdrop-filter: none; } +} diff --git a/.agents/skills/ui-ux-curated-full/snippets/liquid-glass.css b/.agents/skills/ui-ux-curated-full/snippets/liquid-glass.css new file mode 100644 index 0000000..47a8628 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/snippets/liquid-glass.css @@ -0,0 +1,12 @@ +.liquid-shell { + position: relative; + overflow: clip; + background: color-mix(in srgb, Canvas 72%, transparent); + border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); + backdrop-filter: blur(22px) saturate(135%); + -webkit-backdrop-filter: blur(22px) saturate(135%); +} +.liquid-shell::before { + content: ""; position: absolute; inset: 0; pointer-events: none; + background: linear-gradient(135deg, color-mix(in srgb, white 20%, transparent), transparent 42%); +} diff --git a/.agents/skills/ui-ux-curated-full/snippets/liquid-morph.css b/.agents/skills/ui-ux-curated-full/snippets/liquid-morph.css new file mode 100644 index 0000000..c790f5c --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/snippets/liquid-morph.css @@ -0,0 +1,2 @@ +.morph-shell { transform-origin: var(--morph-origin, 50% 50%); transition: transform 220ms cubic-bezier(.2,.8,.2,1), border-radius 220ms cubic-bezier(.2,.8,.2,1), opacity 160ms ease; } +@media (prefers-reduced-motion: reduce) { .morph-shell { transition-duration: 1ms; } } diff --git a/.agents/skills/ui-ux-curated-full/snippets/tailwind-patterns.md b/.agents/skills/ui-ux-curated-full/snippets/tailwind-patterns.md new file mode 100644 index 0000000..6390d15 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/snippets/tailwind-patterns.md @@ -0,0 +1,2 @@ +# Tailwind Pattern Notes +Prefer semantic component classes or CSS variables rather than repeating long visual utility bundles across every component. Keep glass effects centralized in a Surface/Overlay primitive. Use responsive utilities to change layout regions and visibility based on information priority, not only dimensions. diff --git a/.agents/skills/ui-ux-curated-full/snippets/tokens.css b/.agents/skills/ui-ux-curated-full/snippets/tokens.css new file mode 100644 index 0000000..58c94a5 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/snippets/tokens.css @@ -0,0 +1,8 @@ +:root { + --space-1: .25rem; --space-2: .5rem; --space-3: .75rem; --space-4: 1rem; + --space-6: 1.5rem; --space-8: 2rem; + --radius-sm: .5rem; --radius-md: .75rem; --radius-lg: 1rem; + --surface: color-mix(in srgb, Canvas 96%, transparent); + --surface-elevated: color-mix(in srgb, Canvas 99%, transparent); + --border-subtle: color-mix(in srgb, CanvasText 12%, transparent); +} diff --git a/.agents/skills/ui-ux-curated-full/styles/glassmorphism-dashboard.md b/.agents/skills/ui-ux-curated-full/styles/glassmorphism-dashboard.md new file mode 100644 index 0000000..dbd63b2 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/styles/glassmorphism-dashboard.md @@ -0,0 +1,5 @@ +# Glass Dashboard Variant + +Use a solid neutral dashboard canvas. Apply glass only to the global header, floating assistant, quick-action palette, and selected summary panels. Tables/logs remain opaque for readability. + +Preferred hierarchy: canvas → opaque work surfaces → glass floating layer → modal. Status colors appear inside badges/icons, not as tinted glass over entire panels. diff --git a/.agents/skills/ui-ux-curated-full/styles/glassmorphism.md b/.agents/skills/ui-ux-curated-full/styles/glassmorphism.md new file mode 100644 index 0000000..4523494 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/styles/glassmorphism.md @@ -0,0 +1,7 @@ +# Restrained Glassmorphism + +Use for elevated navigation, side panels, command bars, overlays, compact summary cards, and premium shells. The base canvas should remain mostly solid. + +Recipe: translucent surface + modest backdrop blur + subtle 1px border + restrained shadow. Maintain strong foreground contrast. Use one glass elevation level for normal floating surfaces and one stronger level for modals; avoid unique recipes per component. + +Do not place long forms, dense tables, or paragraphs on highly transparent glass. Avoid stacking multiple translucent panels where backgrounds visually collide. diff --git a/.agents/skills/ui-ux-curated-full/styles/liquid-glass-mobile.md b/.agents/skills/ui-ux-curated-full/styles/liquid-glass-mobile.md new file mode 100644 index 0000000..3ccd743 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/styles/liquid-glass-mobile.md @@ -0,0 +1,5 @@ +# Liquid Glass — Mobile + +Best for bottom navigation, floating action clusters, compact tool palettes, and sheets. Keep touch targets generous and text contrast high. The glass surface may visually merge around adjacent controls, but controls remain semantically separate. + +Avoid placing a full scrolling feed on translucent material. Use solid content backgrounds under floating liquid navigation/sheets. diff --git a/.agents/skills/ui-ux-curated-full/styles/liquid-glass.md b/.agents/skills/ui-ux-curated-full/styles/liquid-glass.md new file mode 100644 index 0000000..a781e96 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/styles/liquid-glass.md @@ -0,0 +1,5 @@ +# Liquid Glass + +Use as a dynamic material for floating controls, navigation, media/tool overlays, and adaptive chrome. Visual qualities: smooth translucent material, soft refraction impression, subtle highlights, and motion that suggests a continuous surface. + +Keep the effect bounded. Content itself stays crisp. Motion should preserve spatial continuity and never obscure state changes. Provide a simpler opaque fallback for reduced transparency, low-power, or accessibility contexts. diff --git a/.agents/skills/ui-ux-curated-full/styles/liquid-morph-assistant.md b/.agents/skills/ui-ux-curated-full/styles/liquid-morph-assistant.md new file mode 100644 index 0000000..7c2475f --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/styles/liquid-morph-assistant.md @@ -0,0 +1,5 @@ +# Liquid Morph — Assistant + +A compact assistant affordance can morph into a contextual panel: small orb/button → composer/status capsule → detail sheet. Keep the user's work visible and preserve the anchor location so the transition explains where the panel came from. + +Do not morph large dense content. Morph the shell, then render stable content inside it. diff --git a/.agents/skills/ui-ux-curated-full/styles/liquid-morph.md b/.agents/skills/ui-ux-curated-full/styles/liquid-morph.md new file mode 100644 index 0000000..311b9a1 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/styles/liquid-morph.md @@ -0,0 +1,5 @@ +# Liquid Morph + +Use for focal transformations: assistant opening, command palette expansion, onboarding transitions, creative controls, or a status object morphing into detail. The value is continuity between states, not constant wobble. + +Define explicit source and destination geometry. Use transform/clip-path/mask sparingly, with opacity and scale as robust fallbacks. The final state must become visually stable quickly. diff --git a/.agents/skills/ui-ux-curated-full/templates/assistant-panel.md b/.agents/skills/ui-ux-curated-full/templates/assistant-panel.md new file mode 100644 index 0000000..2f43ac9 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/assistant-panel.md @@ -0,0 +1,2 @@ +# Assistant Panel Template +Header: task/context + compact status. Body: conversation plus structured artifacts. Composer: sticky at bottom. Contextual actions attach to the relevant artifact. Evidence/logs collapse by default. On mobile, assistant occupies a sheet/full-height surface rather than a narrow overlay. diff --git a/.agents/skills/ui-ux-curated-full/templates/command-palette.md b/.agents/skills/ui-ux-curated-full/templates/command-palette.md new file mode 100644 index 0000000..55afb1e --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/command-palette.md @@ -0,0 +1,2 @@ +# Command Palette Template +Fast open, immediate focus, recent/contextual actions first, keyboard navigation, clear grouping, concise descriptions, visible shortcuts, and empty/no-result states. Use glass/liquid material only on the shell; result rows remain high contrast. diff --git a/.agents/skills/ui-ux-curated-full/templates/dashboard-shell.md b/.agents/skills/ui-ux-curated-full/templates/dashboard-shell.md new file mode 100644 index 0000000..f5204e6 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/dashboard-shell.md @@ -0,0 +1,4 @@ +# Dashboard Shell Template +Regions: compact global header; optional navigation rail; page heading with status/context; primary work region; secondary context drawer; transient assistant/command surface. + +Desktop: prioritize one dominant work region, avoid equal-weight card grids. Mobile: nav collapses to top/bottom destination navigation, context drawer becomes sheet, table becomes priority list where needed. diff --git a/.agents/skills/ui-ux-curated-full/templates/design-system-master.md b/.agents/skills/ui-ux-curated-full/templates/design-system-master.md new file mode 100644 index 0000000..eeee0fe --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/design-system-master.md @@ -0,0 +1,14 @@ +# Design System Master +## Product principles +## Layout grid and breakpoints +## Spacing / density +## Typography +## Semantic color tokens +## Surface / elevation / glass rules +## Radius / border / shadow rules +## Core component behavior +## Interaction and motion +## Accessibility +## Responsive conventions +## Do / Don't +## Approved visual references diff --git a/.agents/skills/ui-ux-curated-full/templates/detail-drawer.md b/.agents/skills/ui-ux-curated-full/templates/detail-drawer.md new file mode 100644 index 0000000..078bd60 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/detail-drawer.md @@ -0,0 +1,2 @@ +# Detail Drawer Template +Use when users need to inspect/edit an item without losing collection context. Keep header and key actions sticky, content scrollable, and destructive actions separated. On mobile, transform into full-height sheet/page. diff --git a/.agents/skills/ui-ux-curated-full/templates/empty-state.md b/.agents/skills/ui-ux-curated-full/templates/empty-state.md new file mode 100644 index 0000000..a27122a --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/empty-state.md @@ -0,0 +1,2 @@ +# Empty State Template +Explain what is empty, why it matters, and the next useful action. Use one modest illustration/icon at most. Do not celebrate routine emptiness with oversized marketing art. Differentiate first-use empty, filtered-empty, permission-empty, and error states. diff --git a/.agents/skills/ui-ux-curated-full/templates/form-flow.md b/.agents/skills/ui-ux-curated-full/templates/form-flow.md new file mode 100644 index 0000000..2e31414 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/form-flow.md @@ -0,0 +1,2 @@ +# Form Flow Template +Group by user decision. Persistent labels, helpful defaults, inline validation, clear optionality, save/pending/success/error states. For long forms, use sections with progress only when it actually helps orientation. Preserve values on error. diff --git a/.agents/skills/ui-ux-curated-full/templates/mobile-bottom-sheet.md b/.agents/skills/ui-ux-curated-full/templates/mobile-bottom-sheet.md new file mode 100644 index 0000000..dc25e0d --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/mobile-bottom-sheet.md @@ -0,0 +1,2 @@ +# Mobile Bottom Sheet Template +Use for contextual actions/detail, not core navigation. Include drag handle only if draggable, clear title, close/back semantics, safe-area padding, sticky primary action if needed, and scroll containment. Do not stack sheets. diff --git a/.agents/skills/ui-ux-curated-full/templates/page-override.md b/.agents/skills/ui-ux-curated-full/templates/page-override.md new file mode 100644 index 0000000..1f97642 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/page-override.md @@ -0,0 +1,9 @@ +# Page Override +- Page: +- Master rules inherited: +- Intent: +- Unique information hierarchy: +- Allowed deviations: +- Added components: +- Responsive behavior: +- Evidence/screenshots for acceptance: diff --git a/.agents/skills/ui-ux-curated-full/templates/planner-screen.md b/.agents/skills/ui-ux-curated-full/templates/planner-screen.md new file mode 100644 index 0000000..353ae65 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/planner-screen.md @@ -0,0 +1,2 @@ +# Planner Screen Template +Top: objective + scope. Main: requirements, affected areas, assumptions, dependencies, steps. Side/secondary region: open decisions + missing evidence. Footer/sticky action: approve / request changes. Show architecture impact only when material; avoid forcing a diagram into every task. diff --git a/.agents/skills/ui-ux-curated-full/templates/settings-page.md b/.agents/skills/ui-ux-curated-full/templates/settings-page.md new file mode 100644 index 0000000..cf79379 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/settings-page.md @@ -0,0 +1,2 @@ +# Settings Page Template +Organize by user mental model, not service architecture. Use clear section titles and short explanatory text. Toggle only truly binary settings. Dangerous actions live in a separate danger zone. Save behavior must be explicit: autosave with feedback or clear save button, not ambiguous hybrid behavior. diff --git a/.agents/skills/ui-ux-curated-full/templates/table-toolbar.md b/.agents/skills/ui-ux-curated-full/templates/table-toolbar.md new file mode 100644 index 0000000..f1c06e9 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/table-toolbar.md @@ -0,0 +1,2 @@ +# Table + Toolbar Template +Toolbar order: search, primary filter(s), view/sort, bulk actions only after selection, primary create action. Keep current filter state visible. Columns prioritize decision-making. Row actions should not shift layout. Provide density and column customization only if user value justifies complexity. diff --git a/.agents/skills/ui-ux-curated-full/templates/ui-contract.md b/.agents/skills/ui-ux-curated-full/templates/ui-contract.md new file mode 100644 index 0000000..a8a13ba --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/ui-contract.md @@ -0,0 +1,20 @@ +# UI Contract +- Product/surface: +- User + primary job: +- Existing components/tokens to reuse: +- Primary action: +- Secondary actions: +- Information hierarchy: +- Layout regions: +- Density + spacing scale: +- Typography roles: +- Semantic colors: +- Surface/elevation model: +- Selected style family + where it is allowed: +- Interaction states: +- Loading/empty/error states: +- Responsive transformations: +- Accessibility constraints: +- Motion rules: +- Explicit anti-patterns: +- Acceptance screenshots/viewports: diff --git a/.agents/skills/ui-ux-curated-full/templates/verifier-screen.md b/.agents/skills/ui-ux-curated-full/templates/verifier-screen.md new file mode 100644 index 0000000..85eb128 --- /dev/null +++ b/.agents/skills/ui-ux-curated-full/templates/verifier-screen.md @@ -0,0 +1,2 @@ +# Verifier Screen Template +Summary: READY / FIX LOCAL / REPLAN / HUMAN DECISION. Then criterion-to-evidence rows with PASS/FAIL/UNKNOWN. Separate regression checks, plan deviations, unexpected files, and UI/runtime evidence. Raw logs are inspectable but not the main UI. diff --git a/.agents/skills/ui-visual-verifier/SKILL.md b/.agents/skills/ui-visual-verifier/SKILL.md new file mode 100644 index 0000000..4bc4781 --- /dev/null +++ b/.agents/skills/ui-visual-verifier/SKILL.md @@ -0,0 +1,54 @@ +--- +name: ui-visual-verifier +description: Independently inspect rendered product UI after implementation, classify concrete visual/UX defects, verify responsive and state behavior, and prevent random CSS fix loops. Use after UI changes or when the result looks weak despite correct code. +--- + +# UI Visual Verifier + +Review the **rendered interface**, not just source code. The objective is to find specific observable defects and decide whether the implementation is ready, needs one local fix, or needs design/replanning. + +## Evidence first + +When possible, inspect screenshots or the running UI at relevant viewports and states. If only source is available, mark visual claims as `UNPROVEN` rather than pretending they were observed. + +## Review order + +1. **Task clarity** — can the user identify current state, priority, and next action quickly? +2. **Hierarchy** — are emphasis and grouping proportional to importance? +3. **Layout** — alignment, rhythm, whitespace, density, scrolling, overflow. +4. **Typography** — readable sizes/line lengths, consistent roles, no accidental visual noise. +5. **Components** — consistent controls, radii, elevation, icons, states. +6. **Color/material** — semantic contrast, glass/translucency legibility, no effect overload. +7. **Interaction states** — hover/focus/selected/disabled/loading/error/empty as relevant. +8. **Responsive behavior** — inspect at least desktop and narrow/mobile when applicable. +9. **Accessibility** — obvious contrast, focus, semantics/labels, target size, motion issues. +10. **Product consistency** — does this look like the same product as adjacent surfaces? + +Use `references/defect-taxonomy.md` to classify findings. + +## Anti-loop rule + +Never recommend “tweak spacing/colors until it feels right.” Each fix must name: + +- the observed defect; +- evidence/location; +- likely cause; +- smallest correction; +- what must be re-checked afterward. + +If two visual fixes reveal new unrelated structural defects, stop and return `REPLAN_UI` instead of continuing to patch. + +## Status + +Return one: + +- `UI_READY` +- `FIX_LOCAL` +- `REPLAN_UI` +- `NEEDS_RENDER_EVIDENCE` + +Use `assets/ui-review-report.md` when a structured report helps. + +## Optional local Impeccable integration + +If the project already has the Impeccable CLI/hook installed and shell access is available, its detector output can be used as additional evidence. Do not assume it ran. A clean detector result is not a substitute for inspecting hierarchy, usefulness, or the rendered experience. diff --git a/.agents/skills/ui-visual-verifier/agents/openai.yaml b/.agents/skills/ui-visual-verifier/agents/openai.yaml new file mode 100644 index 0000000..023e019 --- /dev/null +++ b/.agents/skills/ui-visual-verifier/agents/openai.yaml @@ -0,0 +1,15 @@ +interface: + display_name: ui visual verifier + short_description: Independently inspect rendered product UI after implementation, + classify concrete visual/UX defects, verify responsive and state behavior, and + prevent random CSS fix loops. Use after UI changes or when the result looks weak + despite correct code. + icon_small: assets/icon.svg + icon_large: assets/icon.svg +policy: + products: + - chatgpt + - codex + - api + - atlas + allow_implicit_invocation: true diff --git a/.agents/skills/ui-visual-verifier/assets/icon.svg b/.agents/skills/ui-visual-verifier/assets/icon.svg new file mode 100644 index 0000000..f387e96 --- /dev/null +++ b/.agents/skills/ui-visual-verifier/assets/icon.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/.agents/skills/ui-visual-verifier/assets/ui-review-report.md b/.agents/skills/ui-visual-verifier/assets/ui-review-report.md new file mode 100644 index 0000000..917a54e --- /dev/null +++ b/.agents/skills/ui-visual-verifier/assets/ui-review-report.md @@ -0,0 +1,15 @@ +# UI Review + +## Evidence inspected + +## Findings +| ID | Category | Severity | Observed defect | Evidence/location | Smallest correction | Re-check | +|---|---|---|---|---|---|---| + +## Responsive/state coverage + +## Product consistency + +## Remaining unproven areas + +**Status:** UI_READY | FIX_LOCAL | REPLAN_UI | NEEDS_RENDER_EVIDENCE diff --git a/.agents/skills/ui-visual-verifier/references/defect-taxonomy.md b/.agents/skills/ui-visual-verifier/references/defect-taxonomy.md new file mode 100644 index 0000000..3038302 --- /dev/null +++ b/.agents/skills/ui-visual-verifier/references/defect-taxonomy.md @@ -0,0 +1,36 @@ +# UI defect taxonomy + +Classify before fixing. + +## H — Hierarchy +Examples: primary action unclear; every card has equal weight; status and action compete; section titles fail to organize scanning. + +## L — Layout +Examples: misalignment; accidental gaps; cramped clusters; overflow; excessive card nesting; important content below unnecessary chrome. + +## T — Typography +Examples: weak type hierarchy; unreadable size/line-height; too many weights; long line lengths; secondary text too faint. + +## C — Component consistency +Examples: inconsistent button/input shapes; arbitrary radii/shadows; duplicate component patterns; icons from mixed visual languages. + +## M — Material/color +Examples: glass reduces legibility; low contrast; effect overload; gradients/glow used without hierarchy value; semantic colors inconsistent. + +## S — State/interaction +Examples: missing loading/error/empty/selected/disabled state; focus invisible; click target unclear; destructive action insufficiently distinct. + +## R — Responsive +Examples: desktop layout merely squeezed; clipped controls; priority changes lost on mobile; tables unusable; fixed widths cause horizontal scroll. + +## A — Accessibility +Examples: contrast issue; unlabeled control; keyboard focus missing; touch target too small; color-only status; motion ignores reduced-motion preference. + +## P — Product mismatch +Examples: new screen invents a different design language; density differs radically from adjacent workflow; novel visual effect conflicts with product purpose. + +## Severity + +- **Blocker**: prevents task completion, hides critical state, creates accessibility failure, or introduces broken responsive behavior. +- **Major**: materially slows comprehension or makes the product look inconsistent/unreliable. +- **Minor**: polish issue with no meaningful task impact. diff --git a/.agents/skills/verifier/SKILL.md b/.agents/skills/verifier/SKILL.md new file mode 100644 index 0000000..d1dd98f --- /dev/null +++ b/.agents/skills/verifier/SKILL.md @@ -0,0 +1,107 @@ +--- +name: verifier +description: Independently verify a coding change against the plan, acceptance criteria, architecture, regressions, and rendered UI. Produces evidence-backed READY, FIX_LOCAL, REPLAN, or HUMAN_DECISION outcomes. +--- + +# Verifier + +Use this skill after implementation. Prefer a fresh context/agent when the harness supports it. Do not accept the executor's claims as proof. + +## Core rule + +Verification is requirement-by-requirement evidence collection, not a general code review and not “tests passed, therefore done.” + +By default, do not edit code. Diagnose and classify first. + +## Inputs + +Use: +- approved plan and acceptance criteria; +- implementation report; +- actual diff and current repository state; +- tests/build/runtime output; +- incumbent product/design context for UI work. + +## Verification procedure + +### 1. Re-ground independently + +Use Graphify/source inspection to confirm affected paths and dependencies rather than trusting the executor's file list. For architecture-sensitive changes, use Archify or equivalent source-backed flow inspection to verify the intended architecture delta. + +### 2. Verify every requirement + +For each requirement/acceptance criterion, record: +- `PASS`, `FAIL`, or `UNPROVEN`; +- concrete evidence: test, command output, code path, runtime behavior, screenshot/render, API result, or other reproducible proof. + +`UNPROVEN` is not `PASS`. + +### 3. Regression verification + +Check the regression surface from the plan plus any new surface revealed by the diff: +- callers and downstream consumers; +- API/schema compatibility; +- state/error/empty/loading paths; +- permissions/auth boundaries where relevant; +- existing tests around affected behavior; +- build/type integrity; +- unintended files/behaviors changed. + +### 4. Diff review + +Inspect for: +- changes outside the approved scope; +- duplicated abstractions or unnecessary indirection; +- hidden behavior changes; +- dead code or incomplete migrations; +- error handling that masks failures; +- tests that only mirror the implementation rather than prove behavior. + +### 5. UI verification + +For UI-facing changes, verification must include the **rendered result**, not source inspection alone. + +Use Impeccable for deterministic/visual design checks and critique. Verify at least: +- hierarchy and readability; +- layout/alignment/spacing; +- component consistency with the product; +- loading/empty/error/disabled/selected states as relevant; +- responsive behavior at relevant widths; +- obvious accessibility issues; +- whether the implementation respects the planner's UI contract. + +Use UI UX Pro Max as design reference; use Impeccable to inspect what was actually built. + +Do not enter a random CSS tweak loop. Name the observed defect and its likely cause before proposing a fix. + +## Outcome policy + +Return exactly one primary status: + +### `READY` +Every material acceptance criterion is proven and no blocking regression remains. + +### `FIX_LOCAL` +A narrow defect exists, its root cause is proven, the plan remains valid, and one bounded fix should resolve it. Specify the exact defect and re-verification required. + +### `REPLAN` +Use when: +- a material plan assumption is false; +- the change requires broader architecture/scope than planned; +- there is a second unexpected regression; +- repeated local fixes are accumulating; +- verification exposes missing requirements or contradictory acceptance criteria. + +### `HUMAN_DECISION` +A product/architecture/risk decision is genuinely required and cannot safely be inferred from repository evidence. + +## Syntaro profile + +If `.agent-stack/profile` contains `syntaro`, require stronger evidence: +- explicit requirement-to-evidence mapping; +- architecture compliance for changed flows; +- missing-evidence list; +- open decision list; +- verification readiness suitable for another human or agent to audit. + +Never convert uncertainty into a pass merely to complete the task.