mlai-code 0.0.0-stage → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -2
- package/bin/mlai.mjs +3 -0
- package/package.json +18 -3
- package/src/browser-setup.mjs +77 -0
- package/src/cli-ext.mjs +146 -0
- package/src/cli.mjs +534 -0
- package/src/cloud.mjs +29 -0
- package/src/completion.mjs +159 -0
- package/src/credentials.mjs +54 -0
- package/src/deploy.mjs +134 -0
- package/src/distribution.mjs +373 -0
- package/src/engine-key.mjs +4 -0
- package/src/engine.mjs +167 -0
- package/src/headless.mjs +196 -0
- package/src/home.mjs +22 -0
- package/src/host.mjs +123 -0
- package/src/local-models.mjs +64 -0
- package/src/modes.mjs +38 -0
- package/src/netbox.mjs +97 -0
- package/src/netjail.py +59 -0
- package/src/offline.mjs +98 -0
- package/src/parity.mjs +86 -0
- package/src/project.mjs +68 -0
- package/src/relay.mjs +140 -0
- package/src/render.mjs +73 -0
- package/src/restricted.mjs +47 -0
- package/src/review.mjs +70 -0
- package/src/runner.mjs +127 -0
- package/src/runtime.mjs +75 -0
- package/src/sandbox.mjs +135 -0
- package/src/sdk.mjs +11 -0
- package/src/server.mjs +110 -0
- package/src/session.mjs +290 -0
- package/src/settings.mjs +135 -0
- package/src/shared-data.mjs +3 -0
- package/src/tui/acp.mjs +145 -0
- package/src/tui/agents-cli.mjs +114 -0
- package/src/tui/agents-local.mjs +65 -0
- package/src/tui/ansi.mjs +123 -0
- package/src/tui/app.mjs +710 -0
- package/src/tui/approval.mjs +88 -0
- package/src/tui/bg.mjs +172 -0
- package/src/tui/bgterm.mjs +79 -0
- package/src/tui/chat.mjs +230 -0
- package/src/tui/clipboard.mjs +74 -0
- package/src/tui/cloud-cli.mjs +57 -0
- package/src/tui/cloud-run.mjs +123 -0
- package/src/tui/cmd-agents.mjs +130 -0
- package/src/tui/cmd-auto-review.mjs +94 -0
- package/src/tui/cmd-cloud.mjs +17 -0
- package/src/tui/cmd-config.mjs +104 -0
- package/src/tui/cmd-core.mjs +160 -0
- package/src/tui/cmd-distribution.mjs +15 -0
- package/src/tui/cmd-ecosystem.mjs +169 -0
- package/src/tui/cmd-extensibility.mjs +333 -0
- package/src/tui/cmd-remote.mjs +18 -0
- package/src/tui/cmd-review.mjs +58 -0
- package/src/tui/cmd-session-extra.mjs +152 -0
- package/src/tui/cmd-tui.mjs +200 -0
- package/src/tui/commands.mjs +160 -0
- package/src/tui/custom-commands.mjs +98 -0
- package/src/tui/diff.mjs +60 -0
- package/src/tui/editor.mjs +190 -0
- package/src/tui/ext-state.mjs +16 -0
- package/src/tui/extensions-local.mjs +140 -0
- package/src/tui/files.mjs +72 -0
- package/src/tui/handoff.mjs +110 -0
- package/src/tui/import-setups.mjs +151 -0
- package/src/tui/init.mjs +104 -0
- package/src/tui/keymap.mjs +70 -0
- package/src/tui/keys.mjs +101 -0
- package/src/tui/loop.mjs +75 -0
- package/src/tui/markdown.mjs +118 -0
- package/src/tui/mcp-config.mjs +225 -0
- package/src/tui/mcp-oauth.mjs +162 -0
- package/src/tui/permissions.mjs +189 -0
- package/src/tui/plain.mjs +32 -0
- package/src/tui/plugins-local.mjs +103 -0
- package/src/tui/remote.mjs +125 -0
- package/src/tui/review-cli.mjs +332 -0
- package/src/tui/review-github.mjs +59 -0
- package/src/tui/screen.mjs +60 -0
- package/src/tui/session-ops.mjs +104 -0
- package/src/tui/skills-local.mjs +92 -0
- package/src/tui/snapshots.mjs +87 -0
- package/src/tui/statusline.mjs +98 -0
- package/src/tui/transcript.mjs +116 -0
- package/src/two-words.mjs +36 -0
- package/src/wakeups.mjs +53 -0
- package/src/winenv.mjs +94 -0
- package/src/winsandbox.py +351 -0
- package/src/workspace-api.mjs +621 -0
- package/src/worktree.mjs +128 -0
- package/vendor/client-sdk/controller.cjs +115 -0
- package/vendor/client-sdk/files.cjs +38 -0
- package/vendor/client-sdk/index.cjs +133 -0
- package/vendor/client-sdk/login.cjs +52 -0
- package/vendor/client-sdk/updates.cjs +41 -0
- package/vendor/cloud-cli/mlai.mjs +394 -0
- package/worker/architecture_parse.cjs +23 -0
- package/worker/architecture_worker.py +394 -0
- package/worker/ask_first.py +96 -0
- package/worker/attachment_reader.py +66 -0
- package/worker/background_jobs.py +111 -0
- package/worker/brief_questions.py +56 -0
- package/worker/browser_local.py +49 -0
- package/worker/browser_pane.py +89 -0
- package/worker/browser_tool.py +101 -0
- package/worker/build_planner.py +187 -0
- package/worker/chat_fork.py +277 -0
- package/worker/checkpoints.py +133 -0
- package/worker/cloud_pty.py +351 -0
- package/worker/command_policy.py +39 -0
- package/worker/command_safety.py +717 -0
- package/worker/computer_card.sh +23 -0
- package/worker/computer_setup.sh +86 -0
- package/worker/computer_use.py +221 -0
- package/worker/connector_search.py +43 -0
- package/worker/context_manager.py +60 -0
- package/worker/conversation.py +144 -0
- package/worker/deploy_pack.py +116 -0
- package/worker/design_director.py +240 -0
- package/worker/dev_jobs.py +166 -0
- package/worker/edit_guard.py +99 -0
- package/worker/env_setup.py +129 -0
- package/worker/evidence.py +109 -0
- package/worker/fast_search.py +24 -0
- package/worker/git_sync.py +333 -0
- package/worker/goals.py +156 -0
- package/worker/handover.py +98 -0
- package/worker/harness_memory.py +194 -0
- package/worker/image_generation.py +173 -0
- package/worker/intelligence.py +149 -0
- package/worker/intent_model.py +78 -0
- package/worker/intent_weights.json +1 -0
- package/worker/ios_simulator.py +87 -0
- package/worker/kimi_bridge.py +997 -0
- package/worker/kimi_compact.py +93 -0
- package/worker/kimi_gates.py +304 -0
- package/worker/kimi_hook.py +617 -0
- package/worker/lifecycle.py +95 -0
- package/worker/lsp.py +77 -0
- package/worker/mcp_local.py +293 -0
- package/worker/memory.py +99 -0
- package/worker/mlai_auto_review.py +177 -0
- package/worker/mlai_hooks.py +966 -0
- package/worker/mlai_mcp.py +441 -0
- package/worker/mlai_permissions.py +283 -0
- package/worker/model_stream.py +75 -0
- package/worker/nested_repos.py +76 -0
- package/worker/offline_guard.py +17 -0
- package/worker/preview.py +806 -0
- package/worker/proc_watch.py +124 -0
- package/worker/project_context.py +72 -0
- package/worker/project_rules.py +99 -0
- package/worker/quality.py +180 -0
- package/worker/reply_language.py +56 -0
- package/worker/repo_hygiene.py +132 -0
- package/worker/repo_memory.py +101 -0
- package/worker/repo_policy.py +269 -0
- package/worker/roles.json +3173 -0
- package/worker/roles.py +303 -0
- package/worker/runner.py +1795 -0
- package/worker/runtime_control.py +205 -0
- package/worker/secret_scan.py +168 -0
- package/worker/session_hub.py +80 -0
- package/worker/skill_library.py +129 -0
- package/worker/skill_pack.py +533 -0
- package/worker/subagents.py +91 -0
- package/worker/task_controller.py +139 -0
- package/worker/task_skills.py +159 -0
- package/worker/team_checkpoint.py +33 -0
- package/worker/token_count.py +32 -0
- package/worker/tool_catalog.py +38 -0
- package/worker/upload_storage.py +531 -0
- package/worker/verification.py +725 -0
- package/worker/vision.py +84 -0
- package/worker/wakeups.py +63 -0
- package/worker/web_tools.py +203 -0
- package/worker/winproc.py +135 -0
- package/worker/work_ledger.py +117 -0
- package/worker/worktrees.py +79 -0
|
@@ -0,0 +1,533 @@
|
|
|
1
|
+
"""Built-in modern-stack skills (Agent Skills style). Only id + description enter the prompt until a skill is needed.
|
|
2
|
+
|
|
3
|
+
Each skill names the Vault variables it expects; values are provided to commands as environment variables, never pasted in code."""
|
|
4
|
+
|
|
5
|
+
def _s(id, name, description, triggers, content, paths=()):
|
|
6
|
+
return {'id': id, 'name': name, 'description': description, 'triggers': list(triggers), 'paths': list(paths), 'content': content.strip(), 'enabled': True, 'source': 'ML AI Code skill pack'}
|
|
7
|
+
|
|
8
|
+
# Triggers for the starter skills that every workspace receives as files (those files predate triggers).
|
|
9
|
+
STARTER_TRIGGERS = {
|
|
10
|
+
'glm-prd-builder': ['prd', 'product spec', 'specification', 'requirements doc'],
|
|
11
|
+
'glm-ui-workflow': ['design brief', 'replicate', 'clone the ui', 'mockup'],
|
|
12
|
+
'build-app': ['build an app', 'build a', 'create an app', 'make an app', 'new app', 'web app'],
|
|
13
|
+
'debug': ['bug', 'error', 'broken', 'not working', 'fails', 'crash', 'debug', 'fix'],
|
|
14
|
+
'browser-testing': ['browser test', 'test the ui', 'click through', 'e2e'],
|
|
15
|
+
'review': ['review', 'audit', 'code review'],
|
|
16
|
+
'create-skill': ['create a skill', 'reusable skill', 'new skill'],
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
PACK = [
|
|
20
|
+
_s('secrets-and-env', 'Secrets and environment variables', 'Handle API keys, tokens and env vars safely; read values from the Vault instead of hardcoding.',
|
|
21
|
+
['api key', 'secret', 'token', 'env var', 'environment variable', '.env'], '''
|
|
22
|
+
- Never write a secret value into source, tests, commits, logs or chat. Read it from process.env / os.environ.
|
|
23
|
+
- Vault secrets the user enabled for the agent are already exported as environment variables with their Vault names (for example $STRIPE_SECRET_KEY). Check presence with `test -n "$NAME" && echo set`; never echo the value.
|
|
24
|
+
- Local development: write `.env.local` (Next.js) or `.env` and confirm it is in .gitignore before creating it. Commit a `.env.example` with names only.
|
|
25
|
+
- Browser-exposed variables need the framework prefix (NEXT_PUBLIC_, VITE_, EXPO_PUBLIC_). Anything with that prefix is public: only publishable/anon keys belong there.
|
|
26
|
+
- For deploys, set variables on the host (for example `vercel env add NAME production`), not in the repo.
|
|
27
|
+
- If a required secret is missing, stop that step and tell the user the exact Vault name to add, then continue with everything that does not need it.
|
|
28
|
+
'''),
|
|
29
|
+
_s('nextjs-app', 'Next.js App Router', 'Build or change Next.js (App Router) apps: server components, route handlers, env and production builds.',
|
|
30
|
+
['next.js', 'nextjs', 'app router', 'next app', 'react server component'], '''
|
|
31
|
+
- Inspect package.json for the Next.js version and follow the repository's conventions (app/ vs src/app/, middleware.ts or proxy.ts on newer versions).
|
|
32
|
+
- Components are Server Components by default. Add 'use client' only to interactive leaves; keep data fetching and secrets on the server.
|
|
33
|
+
- API endpoints are route handlers: app/api/<name>/route.ts exporting GET/POST. Validate input; return proper status codes.
|
|
34
|
+
- Server-only values must not be imported into client components. Only NEXT_PUBLIC_ variables reach the browser.
|
|
35
|
+
- Use next/image and next/font where they fit; set metadata in layout/page.
|
|
36
|
+
- Verify with `npm run build` (type and build errors) and run `npm run dev -- -H 0.0.0.0 -p 3000` for the preview, then check the main flow with the browser tool on mobile and desktop widths.
|
|
37
|
+
''', ['next.config.*']),
|
|
38
|
+
_s('vercel-deploy', 'Deploy to Vercel', 'Preview and production deployments on Vercel, env variables and build troubleshooting.',
|
|
39
|
+
['vercel', 'deploy', 'deployment', 'preview url', 'go live', 'publish the site'], '''
|
|
40
|
+
Expects Vault: VERCEL_TOKEN (and optionally VERCEL_ORG_ID / VERCEL_PROJECT_ID for an existing project).
|
|
41
|
+
- Make sure `npm run build` passes locally first; fix build errors before deploying.
|
|
42
|
+
- Preview deploy: `npx vercel@latest deploy --yes --token "$VERCEL_TOKEN"`. It prints the preview URL; open it and check the main flow.
|
|
43
|
+
- Production (`--prod`) only when the user explicitly asked for production in this conversation.
|
|
44
|
+
- Env vars: `npx vercel@latest env add NAME preview --token "$VERCEL_TOKEN"` (pipe the value from the env var, never type it). Redeploy after changing env.
|
|
45
|
+
- Failed build: read the build output (`npx vercel@latest inspect <url> --logs --token "$VERCEL_TOKEN"`), reproduce locally, fix, redeploy. Do not retry an unchanged deploy.
|
|
46
|
+
- Report the final URL and what you verified on it.
|
|
47
|
+
''', ['vercel.json']),
|
|
48
|
+
_s('supabase', 'Supabase (database, auth, storage)', 'Supabase Postgres with row level security, auth, storage and migrations.',
|
|
49
|
+
['supabase', 'row level security', 'rls', 'supabase auth'], '''
|
|
50
|
+
Expects Vault: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY (or the publishable key), SUPABASE_SERVICE_ROLE_KEY for server-only admin work, SUPABASE_ACCESS_TOKEN for the CLI.
|
|
51
|
+
- Client: @supabase/supabase-js. For Next.js SSR use @supabase/ssr with separate browser and server clients; refresh sessions in middleware/proxy.
|
|
52
|
+
- Enable row level security on every table you create and add explicit policies (usually `auth.uid() = user_id`). Never rely on client-side filtering for access control.
|
|
53
|
+
- The service-role key bypasses RLS: use it only in server code, never in the browser or NEXT_PUBLIC_ variables.
|
|
54
|
+
- Schema changes go in migrations (`npx supabase migration new <name>`, SQL in supabase/migrations). Keep them idempotent where possible.
|
|
55
|
+
- Verify: sign up a test user, insert and read a row as that user, and confirm another user cannot read it.
|
|
56
|
+
''', ['supabase/*', '*supabase*']),
|
|
57
|
+
_s('postgres-orm', 'Postgres with Neon, Drizzle or Prisma', 'Serverless Postgres (Neon), connection strings, ORM schema and migrations.',
|
|
58
|
+
['neon', 'postgres', 'postgresql', 'drizzle', 'prisma', 'database migration'], '''
|
|
59
|
+
Expects Vault: DATABASE_URL (pooled) and optionally DATABASE_URL_UNPOOLED / DIRECT_URL for migrations.
|
|
60
|
+
- Use the pooled connection for app traffic on serverless hosts and the direct connection for migrations.
|
|
61
|
+
- Drizzle: schema in TypeScript, `npx drizzle-kit generate` then `npx drizzle-kit migrate`. Prisma: `npx prisma migrate dev` locally, `npx prisma migrate deploy` in CI/production.
|
|
62
|
+
- Keep queries parameterized (ORM or tagged templates); never interpolate user input into SQL.
|
|
63
|
+
- Add indexes for columns used in lookups and foreign keys.
|
|
64
|
+
- Verify by running the migration against a dev branch/database and exercising one create/read/update/delete through the app.
|
|
65
|
+
''', ['drizzle.config.*', 'prisma/schema.prisma']),
|
|
66
|
+
_s('clerk-auth', 'Clerk authentication', 'Sign-in, sign-up, protected routes and user sessions with Clerk.',
|
|
67
|
+
['clerk', 'sign in', 'sign up', 'login page', 'authentication', 'protected route'], '''
|
|
68
|
+
Expects Vault: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY.
|
|
69
|
+
- Next.js: install @clerk/nextjs, wrap the root layout in <ClerkProvider>, add clerkMiddleware() in middleware.ts (proxy.ts on newer Next.js) and protect private routes with createRouteMatcher.
|
|
70
|
+
- On the server read the user with auth() / currentUser(); never trust a user id sent from the client.
|
|
71
|
+
- Use Clerk's prebuilt <SignIn/>, <SignUp/>, <UserButton/> unless the user asks for custom UI.
|
|
72
|
+
- Allowed origins / redirect URLs must include the preview and production domains.
|
|
73
|
+
- Verify: signed-out visit to a protected page redirects to sign-in; signed-in user sees their data only.
|
|
74
|
+
'''),
|
|
75
|
+
_s('stripe-payments', 'Stripe payments and subscriptions', 'Stripe Checkout, subscriptions, customer portal and verified webhooks.',
|
|
76
|
+
['stripe', 'checkout', 'payment', 'payments', 'subscription', 'billing'], '''
|
|
77
|
+
Expects Vault: STRIPE_SECRET_KEY (use sk_test_ keys while building), STRIPE_WEBHOOK_SECRET, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY when using Stripe.js.
|
|
78
|
+
- Create Checkout Sessions on the server with Price IDs defined in Stripe; never accept amounts or prices from the client.
|
|
79
|
+
- Fulfil orders from webhooks, not the success redirect. Verify signatures with stripe.webhooks.constructEvent(rawBody, signature, STRIPE_WEBHOOK_SECRET); the handler must read the raw request body.
|
|
80
|
+
- Make webhook handling idempotent (store processed event ids). Handle checkout.session.completed, customer.subscription.updated/deleted, invoice.payment_failed as needed.
|
|
81
|
+
- Use the Billing customer portal for plan changes and cancellation unless custom UI is requested.
|
|
82
|
+
- Never switch to live keys unless the user explicitly asks. Test with card 4242 4242 4242 4242 and `stripe listen --forward-to localhost:3000/api/stripe/webhook` when the CLI is available.
|
|
83
|
+
''', ['*stripe*']),
|
|
84
|
+
_s('email-resend', 'Transactional email with Resend', 'Send transactional emails (welcome, receipts, magic links) with Resend and React Email.',
|
|
85
|
+
['resend', 'send email', 'transactional email', 'email notification', 'react email'], '''
|
|
86
|
+
Expects Vault: RESEND_API_KEY.
|
|
87
|
+
- Send from the server only. Until the user verifies a domain, use the testing sender onboarding@resend.dev, which only delivers to the account owner's address.
|
|
88
|
+
- Build templates with React Email components or simple HTML with a plain-text fallback.
|
|
89
|
+
- Never email real users from tests; use a test recipient and log the message id returned by the API.
|
|
90
|
+
- Handle failures (rate limits, invalid address) and show the user a clear message.
|
|
91
|
+
'''),
|
|
92
|
+
_s('cloudflare-workers', 'Cloudflare Workers, R2 and KV', 'Deploy Workers, use R2/KV/D1 bindings and manage secrets with Wrangler.',
|
|
93
|
+
['cloudflare', 'workers', 'wrangler', 'r2', 'durable object', 'd1'], '''
|
|
94
|
+
Expects Vault: CLOUDFLARE_API_TOKEN (and CLOUDFLARE_ACCOUNT_ID).
|
|
95
|
+
- Configure in wrangler.toml / wrangler.jsonc; bindings (R2, KV, D1) are declared there and accessed on env, not imported.
|
|
96
|
+
- Local: `npx wrangler dev`. Secrets: `npx wrangler secret put NAME` (pipe from env). Deploy: `npx wrangler deploy` after the user approves publishing.
|
|
97
|
+
- Workers are not Node: prefer Web APIs (fetch, Request, Response, crypto.subtle); enable nodejs_compat only when needed.
|
|
98
|
+
- Verify with `curl` against the dev server and the deployed URL.
|
|
99
|
+
''', ['wrangler.*']),
|
|
100
|
+
_s('error-monitoring', 'Sentry error monitoring', 'Add Sentry error and performance monitoring with source maps.',
|
|
101
|
+
['sentry', 'error monitoring', 'error tracking', 'crash reporting'], '''
|
|
102
|
+
Expects Vault: SENTRY_DSN (or NEXT_PUBLIC_SENTRY_DSN) and SENTRY_AUTH_TOKEN for source map upload.
|
|
103
|
+
- Next.js: `npx @sentry/wizard@latest -i nextjs` sets up config files; review its changes before keeping them.
|
|
104
|
+
- Keep the DSN in env; upload source maps only in CI/production builds with the auth token.
|
|
105
|
+
- Set a sensible tracesSampleRate (for example 0.1) and scrub PII.
|
|
106
|
+
- Verify by triggering a test error in a dev route and confirming the event in the Sentry project.
|
|
107
|
+
'''),
|
|
108
|
+
_s('product-analytics', 'PostHog analytics and feature flags', 'Product analytics, events, funnels and feature flags with PostHog.',
|
|
109
|
+
['posthog', 'analytics', 'feature flag', 'product analytics', 'funnel'], '''
|
|
110
|
+
Expects Vault: NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST (for example https://us.i.posthog.com).
|
|
111
|
+
- Initialize posthog-js once in a client provider; capture named events for key actions (signup_completed, checkout_started).
|
|
112
|
+
- Identify users after sign-in with a stable id; do not send emails or secrets as properties unless the user wants that.
|
|
113
|
+
- Respect consent where required; disable capture in tests.
|
|
114
|
+
- Verify that events appear in PostHog's live events view from the preview URL.
|
|
115
|
+
'''),
|
|
116
|
+
_s('ai-features', 'AI features with the AI SDK', 'Add chat, streaming and tool-calling AI features using the Vercel AI SDK or provider SDKs.',
|
|
117
|
+
['ai sdk', 'chatbot', 'llm', 'openai', 'anthropic', 'ai feature', 'streaming chat'], '''
|
|
118
|
+
Expects Vault: the provider key the user chose (OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, ...).
|
|
119
|
+
- Call models only from the server (route handler / server action). Never expose provider keys to the browser.
|
|
120
|
+
- With the AI SDK (`ai` package): streamText on the server returning a streaming response, useChat on the client. Read the installed version's docs before using APIs; they change between majors.
|
|
121
|
+
- Add input limits, rate limiting per user and error states; stream partial output for responsiveness.
|
|
122
|
+
- Verify with one real prompt end to end and one failure case (missing key -> clear message).
|
|
123
|
+
'''),
|
|
124
|
+
_s('github-actions-ci', 'GitHub Actions CI', 'Create or fix GitHub Actions workflows for tests, builds and deploys.',
|
|
125
|
+
['github actions', 'ci pipeline', 'continuous integration', 'workflow file', 'ci'], '''
|
|
126
|
+
- Workflows live in .github/workflows/*.yml. Trigger on pull_request and push to the default branch.
|
|
127
|
+
- Use official actions (actions/checkout, actions/setup-node or setup-python) with dependency caching; run install, lint, typecheck, test, build as separate steps.
|
|
128
|
+
- Secrets come from repository settings (secrets.NAME); never echo them. Set least-privilege `permissions:`.
|
|
129
|
+
- Validate YAML locally (`python -c "import yaml,sys;yaml.safe_load(open(sys.argv[1]))" file`) and keep commands identical to what passes locally.
|
|
130
|
+
''', ['.github/workflows/*']),
|
|
131
|
+
_s('expo-mobile', 'Mobile apps with Expo', 'Build iOS/Android apps with Expo and React Native, previewable on the web.',
|
|
132
|
+
['expo', 'react native', 'mobile app', 'ios app', 'android app'], '''
|
|
133
|
+
Expects Vault (for cloud builds only): EXPO_TOKEN.
|
|
134
|
+
- New app: `npx create-expo-app@latest <name>`; use Expo Router for navigation.
|
|
135
|
+
- Preview in this workspace with the web target: `npx expo start --web --port 3000` (install react-native-web and react-dom if prompted), then check it with the browser tool at phone width.
|
|
136
|
+
- Use EXPO_PUBLIC_ for client-visible config; keep secrets on a backend.
|
|
137
|
+
- Native builds/store submission use EAS (`npx eas-cli build`) and need the user's Expo account; ask before starting them.
|
|
138
|
+
''', ['app.json', 'eas.json']),
|
|
139
|
+
_s('e2e-playwright', 'End-to-end tests with Playwright', 'Write and run Playwright end-to-end tests for web apps, including mobile viewports.',
|
|
140
|
+
['playwright', 'e2e', 'end to end test', 'end-to-end test', 'ui test'], '''
|
|
141
|
+
- Use @playwright/test with a webServer entry in playwright.config.ts that starts the app on port 3000.
|
|
142
|
+
- Prefer role- and label-based locators (getByRole, getByLabel) over CSS selectors; assert visible outcomes, not implementation details.
|
|
143
|
+
- Add a mobile project (for example devices['iPhone 13']) alongside desktop Chromium.
|
|
144
|
+
- Run `npx playwright test --reporter=line`; record the result with the verify tool.
|
|
145
|
+
''', ['playwright.config.*', '*.spec.ts']),
|
|
146
|
+
_s('ui-shadcn-tailwind', 'UI with shadcn/ui and Tailwind', 'Polished, accessible UI using Tailwind CSS and shadcn/ui components.',
|
|
147
|
+
['shadcn', 'tailwind', 'ui components', 'design system', 'beautiful ui', 'landing page'], '''
|
|
148
|
+
- Check the installed Tailwind version: v4 is CSS-first (`@import "tailwindcss";` and @theme in CSS), v3 uses tailwind.config.
|
|
149
|
+
- shadcn/ui: `npx shadcn@latest init`, then `npx shadcn@latest add button card dialog ...`; components are copied into the repo and can be edited.
|
|
150
|
+
- Build with a clear type scale, consistent spacing, real content (no lorem ipsum), visible focus states, and responsive layouts from 360px up.
|
|
151
|
+
- Cover loading, empty and error states. Check contrast and test at mobile and desktop widths with the browser tool.
|
|
152
|
+
''', ['components.json', 'tailwind.config.*']),
|
|
153
|
+
# Role skills: mapped to engineering roles (worker/roles.json) and loaded first when that role is active.
|
|
154
|
+
_s('backend-api', 'Backend APIs and services', 'Design and build production APIs: contracts, validation, errors, pagination, idempotency, auth and tests.',
|
|
155
|
+
['rest api', 'api endpoint', 'graphql', 'openapi', 'backend service', 'webhook'], '''
|
|
156
|
+
- Contract first: resources, request/response schemas, status codes and an error shape like {error:{code,message,details}}. Keep it in openapi.yaml or typed schemas (zod/pydantic) that the handlers import.
|
|
157
|
+
- Validate at the boundary and reject unknown fields. Never trust client ids for authorization: load the object and check ownership on every access.
|
|
158
|
+
- Writes: idempotency keys for retried POSTs, transactions around multi-row changes, optimistic concurrency (version/updated_at) where edits collide.
|
|
159
|
+
- Lists: cursor pagination with a stable sort, limits capped server-side, filters indexed in the database.
|
|
160
|
+
- External calls: timeouts, retries with jitter only for idempotent requests, circuit-break noisy dependencies. Move slow work to a queue/worker and expose job status.
|
|
161
|
+
- Observability: structured JSON logs with request id, latency and status; health (/healthz) and readiness endpoints.
|
|
162
|
+
- Tests: API tests against a real local database (docker compose or SQLite for small apps), covering happy path, validation errors, authz denial and pagination. Show one curl example per endpoint in the summary.
|
|
163
|
+
- Expects Vault: DATABASE_URL for the real database; any third-party API keys the service calls (for example STRIPE_SECRET_KEY). Never hardcode them.
|
|
164
|
+
'''),
|
|
165
|
+
_s('docker-containers', 'Docker and containers', 'Production Dockerfiles and docker compose for local stacks: multi-stage, small, non-root, cached.',
|
|
166
|
+
['docker', 'dockerfile', 'container', 'docker compose', 'containerize'], '''
|
|
167
|
+
- Multi-stage builds: install deps in a builder stage with lockfile-only copy first for cache hits, copy the build output into a slim runtime (distroless, -slim or alpine when compatible).
|
|
168
|
+
- Pin base images by version (and digest for production). Run as a non-root USER, set WORKDIR, expose one port, add HEALTHCHECK when the platform does not provide one.
|
|
169
|
+
- .dockerignore excludes .git, node_modules, .env*, build caches and test artefacts.
|
|
170
|
+
- Config comes from env vars at runtime; never bake secrets into layers or build args.
|
|
171
|
+
- docker compose for local dependencies (postgres, redis, minio) with named volumes and healthchecks; services wait on service_healthy.
|
|
172
|
+
- Validate: `docker build .` (or `docker buildx build --check`) and `hadolint Dockerfile` when available; report the final image size.
|
|
173
|
+
- Expects Vault: REGISTRY_USERNAME and REGISTRY_PASSWORD (or GHCR_TOKEN) only when pushing images.
|
|
174
|
+
''', ['Dockerfile', '*.dockerfile', 'docker-compose*.yml', 'compose*.yml']),
|
|
175
|
+
_s('kubernetes-deploy', 'Kubernetes and Helm', 'Deploy services to Kubernetes with Helm or Kustomize: probes, resources, rollouts, config and secrets.',
|
|
176
|
+
['kubernetes', 'k8s', 'helm', 'kustomize', 'kubectl', 'eks', 'gke', 'aks'], '''
|
|
177
|
+
- Deployment with readiness and liveness probes on distinct endpoints, resource requests and limits, a PodDisruptionBudget and at least 2 replicas for stateless services.
|
|
178
|
+
- RollingUpdate with maxUnavailable 0 for user-facing services; HorizontalPodAutoscaler on CPU or a custom metric.
|
|
179
|
+
- Config via ConfigMap, secrets via ExternalSecrets/Sealed Secrets or the cloud secret manager. Never commit raw Secret manifests with values.
|
|
180
|
+
- securityContext: runAsNonRoot, readOnlyRootFilesystem where possible, drop ALL capabilities. NetworkPolicy to restrict traffic.
|
|
181
|
+
- Validate with `helm lint`, `helm template | kubeconform -strict` or `kubectl apply --dry-run=server` when a cluster is available. Never apply to a real cluster without approval.
|
|
182
|
+
- Expects Vault: KUBECONFIG contents (or a cloud credential such as AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY) to apply to a real cluster; without it, render and validate manifests locally.
|
|
183
|
+
''', ['k8s/*', 'kubernetes/*', 'helm/*', 'charts/*', 'kustomization.yaml']),
|
|
184
|
+
_s('terraform-iac', 'Terraform and infrastructure as code', 'Cloud infrastructure with Terraform/OpenTofu: modules, remote state, plans and safe changes.',
|
|
185
|
+
['terraform', 'opentofu', 'infrastructure as code', 'iac', 'pulumi', 'cloudformation'], '''
|
|
186
|
+
- Structure: root modules per environment, reusable modules with typed variables and outputs, providers pinned with required_providers and a committed lock file.
|
|
187
|
+
- Remote state with locking (S3+DynamoDB, GCS, Terraform Cloud). Never commit state or .tfvars that contain secrets.
|
|
188
|
+
- Tag every resource (owner, env, service). Least-privilege IAM; no wildcard actions on production resources.
|
|
189
|
+
- Workflow: `terraform fmt -check`, `terraform validate`, `tflint`/`checkov` when available, then `terraform plan -out` and show the plan summary. Applying requires explicit user approval.
|
|
190
|
+
- Prefer managed services and data sources over hand-built ones; document cost-relevant choices (instance sizes, NAT gateways, egress).
|
|
191
|
+
- Expects Vault: Cloud credentials such as AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, GOOGLE_CREDENTIALS or ARM_CLIENT_ID/ARM_CLIENT_SECRET for plan/apply; without them run init -backend=false, validate and fmt.
|
|
192
|
+
''', ['*.tf', '*.tfvars', 'Pulumi.yaml']),
|
|
193
|
+
_s('observability-otel', 'Observability with OpenTelemetry', 'Traces, metrics and structured logs with OpenTelemetry; dashboards that answer real questions.',
|
|
194
|
+
['opentelemetry', 'otel', 'tracing', 'metrics', 'observability', 'structured logging'], '''
|
|
195
|
+
- Use the OpenTelemetry SDK and auto-instrumentation for the framework; export OTLP to the collector or vendor configured via env (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME).
|
|
196
|
+
- Propagate trace context across HTTP, queues and background jobs. Add spans around external calls and expensive work with meaningful attributes, never secrets or PII.
|
|
197
|
+
- Metrics: RED for request-driven services (rate, errors, duration histograms), USE for resources, business counters for key events. Keep label cardinality bounded.
|
|
198
|
+
- Logs: structured JSON with trace_id/span_id, level, message and stable keys.
|
|
199
|
+
- Ship one dashboard per service: golden signals plus the top dependencies.
|
|
200
|
+
- Expects Vault: OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS (or SENTRY_DSN, DATADOG_API_KEY, GRAFANA_CLOUD_TOKEN) to ship telemetry.
|
|
201
|
+
'''),
|
|
202
|
+
_s('sre-reliability', 'SRE: SLOs, alerting and runbooks', 'Service level objectives, burn-rate alerts, runbooks, incident response and resilience patterns.',
|
|
203
|
+
['slo', 'sli', 'error budget', 'runbook', 'on-call', 'incident', 'postmortem', 'reliability'], '''
|
|
204
|
+
- Define SLIs from the user's perspective (availability of key requests, latency at p95/p99, freshness for pipelines). Pick SLOs with error budgets (for example 99.9% over 28 days).
|
|
205
|
+
- Alert on multi-window burn rate (for example 2% budget in 1h and 5% in 6h), not on raw CPU. Every alert links a runbook and a dashboard.
|
|
206
|
+
- Runbook template: summary, impact, dashboards, diagnosis steps, mitigations (with exact commands), escalation, rollback.
|
|
207
|
+
- Resilience: timeouts everywhere, bounded retries with jitter, circuit breakers, load shedding, graceful degradation and idempotent consumers.
|
|
208
|
+
- Validate rules with `promtool check rules` (or the vendor's validator). Blameless postmortems: timeline, contributing factors, action items with owners.
|
|
209
|
+
- Expects Vault: Monitoring credentials when wiring real alerts (GRAFANA_CLOUD_TOKEN, PAGERDUTY_TOKEN, DATADOG_API_KEY); otherwise commit rules and runbooks as code.
|
|
210
|
+
''', ['*alerts*.yml', '*rules*.yml', 'runbooks/*']),
|
|
211
|
+
_s('security-appsec', 'Application security', 'Threat modelling, OWASP Top 10 fixes, dependency and secret scanning, secure defaults.',
|
|
212
|
+
['security', 'vulnerability', 'owasp', 'xss', 'csrf', 'sql injection', 'ssrf', 'threat model', 'pentest'], '''
|
|
213
|
+
- Threat model with STRIDE per entry point: what can be spoofed, tampered, disclosed, denied or elevated. Rank by likelihood x impact.
|
|
214
|
+
- Injection: parameterised queries/ORM only; no string-built SQL or shell. Output-encode by context; sanitise HTML with an allow-list.
|
|
215
|
+
- AuthN/AuthZ: check authorization server-side on every object (IDOR); short-lived sessions; secure, HttpOnly, SameSite cookies; CSRF tokens for cookie-authenticated writes.
|
|
216
|
+
- SSRF: allow-list outbound hosts, block private ranges and metadata IPs, disable redirects to new hosts.
|
|
217
|
+
- Headers: CSP, HSTS, X-Content-Type-Options, frame-ancestors. Rate-limit auth and expensive endpoints.
|
|
218
|
+
- Scan: `npm audit --omit=dev`/`pip-audit`, `semgrep --config auto`, `gitleaks detect`, `trivy fs .` when available. Report findings with severity, evidence and fix; never echo secret values.
|
|
219
|
+
- Every fix gets a regression test that reproduces the exploit.
|
|
220
|
+
- Expects Vault: nothing by default; SNYK_TOKEN or GITHUB_TOKEN only for hosted scanners. Never print secrets found during a scan; report their file and line only.
|
|
221
|
+
''', ['SECURITY.md']),
|
|
222
|
+
_s('qa-automation', 'QA and test automation', 'Risk-based test strategy, deterministic automated tests, contract tests and flaky-test triage.',
|
|
223
|
+
['test strategy', 'test automation', 'flaky test', 'coverage', 'regression test', 'qa'], '''
|
|
224
|
+
- Start with a risk map: critical journeys, money/data-loss paths, boundaries and error handling. Test those first.
|
|
225
|
+
- Pyramid: many fast unit tests, contract or integration tests at service boundaries (real database in a container), few end-to-end journeys.
|
|
226
|
+
- Determinism: fixed clocks and seeds, no sleeps (wait for conditions), isolated data per test, cleanup in teardown, no reliance on test order.
|
|
227
|
+
- Assert user-visible behaviour and exact outputs, including error messages and status codes. A mock that records calls does not prove state changed.
|
|
228
|
+
- Flaky tests: reproduce with repeat runs (`--repeat-each`, `pytest -p no:randomly --count`), find the race or shared state, fix or quarantine with an owner.
|
|
229
|
+
- Report: which journeys are covered, what is not, and how long the suite takes.
|
|
230
|
+
- Expects Vault: Test-account credentials (TEST_USER_EMAIL, TEST_USER_PASSWORD) when flows need login; never use production accounts.
|
|
231
|
+
'''),
|
|
232
|
+
_s('data-pipelines', 'Data pipelines and warehouses', 'Idempotent batch and streaming pipelines with dbt/Airflow/Dagster, contracts and data-quality tests.',
|
|
233
|
+
['etl', 'elt', 'data pipeline', 'dbt', 'airflow', 'dagster', 'warehouse', 'ingestion'], '''
|
|
234
|
+
- Layers: raw/landing (append-only), staging (typed, deduplicated), marts (business entities). Name models by layer.
|
|
235
|
+
- Idempotency: every job takes a partition/date range and can be re-run safely (MERGE/upsert or partition overwrite). Support backfills.
|
|
236
|
+
- Incremental loads keyed on a reliable updated_at or CDC offset; handle late-arriving and deleted records.
|
|
237
|
+
- Contracts: declare schemas (dbt contracts, pydantic, JSON Schema) and fail fast on drift. Tests: not_null, unique, accepted_values, relationships, freshness and row-count deltas.
|
|
238
|
+
- Orchestrate with the repo's tool; set retries, SLAs and alerts. Keep credentials in env/secret manager.
|
|
239
|
+
- Prove with a run on a small sample or fixtures and show the test results; never put invented rows in production pipeline code.
|
|
240
|
+
- Expects Vault: Warehouse and source credentials such as DATABASE_URL, BIGQUERY_CREDENTIALS, SNOWFLAKE_PASSWORD, AWS_ACCESS_KEY_ID, STRIPE_SECRET_KEY.
|
|
241
|
+
''', ['dbt_project.yml', 'dags/*', '*.sql']),
|
|
242
|
+
_s('data-analysis', 'Data analysis and experimentation', 'Reproducible analysis, honest statistics, A/B test reads and clear findings reports.',
|
|
243
|
+
['analysis', 'a/b test', 'statistics', 'notebook', 'pandas', 'cohort', 'forecast'], '''
|
|
244
|
+
- Write down the question, metric definition, population and time window before analysing.
|
|
245
|
+
- Profile the data: row counts, missingness, duplicates, outliers, time coverage, leakage between features and outcome.
|
|
246
|
+
- Reproducibility: scripts or notebooks with pinned seeds and package versions; save intermediate outputs and charts to files.
|
|
247
|
+
- Statistics: report effect sizes with confidence intervals; check sample ratio mismatch for A/B tests; correct for multiple comparisons; prefer pre-registered primary metrics.
|
|
248
|
+
- Every number in the summary must come from code that ran. State limitations and what would change the conclusion.
|
|
249
|
+
- Expects Vault: DATABASE_URL or warehouse credentials when the data lives in a database; otherwise the files in the repository.
|
|
250
|
+
'''),
|
|
251
|
+
_s('ml-training', 'Model training and fine-tuning', 'Config-driven training and fine-tuning (PyTorch, Transformers, TRL, PEFT/LoRA) with honest evaluation.',
|
|
252
|
+
['fine-tune', 'finetune', 'lora', 'training', 'pytorch', 'sft', 'grpo', 'dpo', 'distillation', 'hugging face'], '''
|
|
253
|
+
- Define task, metric and baseline first; freeze the evaluation set and check for train/test contamination.
|
|
254
|
+
- Config-driven runs (YAML or dataclass): model, data paths, seed, lr schedule, batch/grad-accum, sequence length, precision (bf16), checkpoint interval. Log to a file and MLflow/W&B if configured.
|
|
255
|
+
- Fine-tuning LLMs: start with LoRA/QLoRA (PEFT) unless full fine-tune is justified; use TRL SFTTrainer/DPOTrainer/GRPOTrainer; apply the chat template; pack sequences; gradient checkpointing for memory.
|
|
256
|
+
- Estimate memory: weights (params x bytes) + optimizer states + activations; state the GPU (for example 1x A100 80GB) and expected hours.
|
|
257
|
+
- Without a GPU here: run a smoke test on a tiny subset (a few steps, tiny model or reduced length) to prove the pipeline, and give the exact command for the full run.
|
|
258
|
+
- Evaluation: compare to the baseline on the frozen set with the same decoding settings; save metrics as JSON; never report numbers that were not produced by a run.
|
|
259
|
+
- Expects Vault: HF_TOKEN for gated models and datasets, WANDB_API_KEY for experiment tracking when used.
|
|
260
|
+
''', ['train*.py', '*finetune*', 'configs/*.yaml']),
|
|
261
|
+
_s('mlops-lifecycle', 'MLOps lifecycle', 'Versioned data, tracked experiments, model registry, serving, promotion gates and drift monitoring.',
|
|
262
|
+
['mlops', 'mlflow', 'model registry', 'model serving', 'vllm', 'drift', 'dvc', 'feature store'], '''
|
|
263
|
+
- Version data (DVC/lakeFS or immutable object paths) and code together; every model artefact records data version, code commit, config and metrics.
|
|
264
|
+
- Track experiments in MLflow or W&B; register models with stages (staging/production) and promotion gated on evaluation thresholds checked in CI.
|
|
265
|
+
- Serving: choose the engine (vLLM/TGI for LLMs, Triton/BentoML/FastAPI for others); containerise with health/readiness, request batching, timeouts, and explicit GPU/CPU resources; autoscale on queue depth or latency.
|
|
266
|
+
- Rollouts: shadow or canary with automatic rollback on error/latency regression.
|
|
267
|
+
- Monitoring: latency, throughput, cost per 1k requests, input/prediction drift (PSI/KS), and data quality on features; alert with runbooks.
|
|
268
|
+
- Validate locally (docker build, a sample inference, pipeline dry run); never push to production registries or clusters without approval.
|
|
269
|
+
- Expects Vault: MLFLOW_TRACKING_URI (and credentials), HF_TOKEN, registry and cloud credentials for deploying model servers.
|
|
270
|
+
''', ['MLproject', 'dvc.yaml', 'bentofile.yaml']),
|
|
271
|
+
_s('llm-rag-agents', 'LLM apps, RAG and agents', 'Production LLM features: real model calls, retrieval with citations, tool-using agents, guardrails and evals.',
|
|
272
|
+
['llm', 'rag', 'retrieval', 'embeddings', 'vector', 'agent', 'chatbot', 'prompt', 'evals', 'tool calling'], '''
|
|
273
|
+
- Call models server-side with keys from env; stream tokens; set max tokens, timeouts and retries; log model, tokens, latency and cost per request.
|
|
274
|
+
- Prompts live in versioned files with variables, not scattered strings. Use structured outputs (JSON schema) for anything parsed.
|
|
275
|
+
- RAG: chunk by document structure (headings, ~300-800 tokens with overlap), store embeddings in a real index (pgvector, the project's vector DB), hybrid search when keywords matter, rerank, cite source ids, and answer "not found" when retrieval is weak.
|
|
276
|
+
- Agents: typed tool schemas, step and cost limits, approval for side-effecting tools, idempotent tools, full traces of messages and tool calls.
|
|
277
|
+
- Guardrails: input/output checks for PII and prompt injection from retrieved content; never execute model-written code without a sandbox.
|
|
278
|
+
- Evals: a golden set (20-200 cases) with expected answers or rubrics; run it on each change; report accuracy, faithfulness, latency and cost. Fake model replies belong only in unit tests.
|
|
279
|
+
- Expects Vault: OPENAI_API_KEY, ANTHROPIC_API_KEY or the model gateway key the app uses; vector store credentials such as PINECONE_API_KEY or DATABASE_URL for pgvector.
|
|
280
|
+
''', ['evals/*', 'prompts/*']),
|
|
281
|
+
_s('aiops-automation', 'AIOps: detection, correlation and remediation', 'Anomaly detection on telemetry, alert correlation into incidents, and approval-gated auto-remediation.',
|
|
282
|
+
['aiops', 'anomaly detection', 'alert correlation', 'root cause', 'auto-remediation', 'self-healing'], '''
|
|
283
|
+
- Data: pull metrics/logs/traces/events from existing sources (Prometheus, OTel, Loki/ELK, cloud monitoring); attach service, owner and deploy metadata.
|
|
284
|
+
- Detection: seasonal baselines (STL/Holt-Winters), robust z-score on residuals, change-point detection for deploy-related shifts; log template mining (Drain) for new error patterns. Start explainable; add ML only when it beats these.
|
|
285
|
+
- Correlation: group alerts by service topology, time window and shared deploys/config changes into one incident with a probable cause and evidence links.
|
|
286
|
+
- Remediation: runbook actions as code with dry-run, blast-radius limits, rate limits and human approval for restarts, scaling or rollbacks; audit every action.
|
|
287
|
+
- Evaluate on replayed historical incidents: precision, recall, time-to-detect and alert-noise reduction; report false positives honestly.
|
|
288
|
+
- Expects Vault: Read access to telemetry (DATADOG_API_KEY, PROMETHEUS_URL, PAGERDUTY_TOKEN). Remediation actions need explicitly scoped credentials and stay behind approval.
|
|
289
|
+
'''),
|
|
290
|
+
_s('embedded-firmware', 'Embedded firmware', 'Firmware for microcontrollers: toolchains, HAL boundaries, interrupts, memory budgets and host tests.',
|
|
291
|
+
['firmware', 'embedded', 'microcontroller', 'arduino', 'esp32', 'stm32', 'rtos', 'usb hid'], '''
|
|
292
|
+
- Identify the target, toolchain and build system already in the repo (MPLAB XC8, arm-none-eabi-gcc, ESP-IDF, PlatformIO, Zephyr) and use them; do not switch stacks.
|
|
293
|
+
- Keep hardware access behind a thin HAL; put protocol and state logic in plain C that compiles and unit-tests on the host (Unity/CMock or a tiny assert harness).
|
|
294
|
+
- Interrupt safety: keep ISRs short, use volatile and atomic access for shared state, avoid malloc in ISRs and hot paths.
|
|
295
|
+
- Respect memory budgets: report flash/RAM use after builds (size tool output); avoid large stack buffers.
|
|
296
|
+
- Never guess register addresses, descriptors or timings: cite the datasheet section or existing headers. List behaviour that needs on-device verification.
|
|
297
|
+
- Expects Vault: nothing by default; toolchains and hardware access are local. Signing keys for production firmware stay out of the repository.
|
|
298
|
+
''', ['*.ino', 'platformio.ini', '*.ld', 'sdkconfig']),
|
|
299
|
+
_s('architecture-adr', 'Architecture and ADRs', 'System design docs, option trade-offs, ADRs, C4 diagrams and phased migration plans.',
|
|
300
|
+
['architecture', 'system design', 'adr', 'design doc', 'rfc', 'trade-off'], '''
|
|
301
|
+
- Requirements first: functional scope, scale (users, requests/s, data size), latency, consistency, availability, cost, compliance and team constraints. Mark assumptions.
|
|
302
|
+
- Options: at least two credible designs compared on the requirements, with risks and cost. Choose one and record it as an ADR (docs/adr/NNNN-title.md: context, decision, consequences, alternatives).
|
|
303
|
+
- Diagrams: C4 context and container views in Mermaid; show data flows and trust boundaries.
|
|
304
|
+
- Failure modes: what happens when each dependency is slow or down; data migration and rollback plans.
|
|
305
|
+
- Delivery: reversible increments, the riskiest assumption proven first with a spike, and measurable success criteria.
|
|
306
|
+
- Expects Vault: nothing by default.
|
|
307
|
+
''', ['docs/adr/*', 'ARCHITECTURE.md']),
|
|
308
|
+
_s('accessibility-wcag', 'Accessibility (WCAG 2.2 AA)', 'Make interfaces usable with keyboard, screen readers and low vision; audit and fix against WCAG 2.2 AA.',
|
|
309
|
+
['accessibility', 'a11y', 'wcag', 'screen reader', 'aria', 'keyboard navigation', 'contrast'], '''
|
|
310
|
+
- Expects Vault: nothing by default.
|
|
311
|
+
- Semantics first: native elements (button, a, label, nav, main, h1-h6) before ARIA. Every form control has a visible label or aria-label; every image an alt (empty alt for decoration).
|
|
312
|
+
- Keyboard: all interactive elements reachable in a sensible order, visible focus ring (never outline:none without a replacement), Escape closes dialogs, focus is trapped in modals and returned on close.
|
|
313
|
+
- Contrast at least 4.5:1 for text and 3:1 for large text and UI boundaries; do not convey state by colour alone. Respect prefers-reduced-motion.
|
|
314
|
+
- Live regions (aria-live=polite) for async status; announce errors next to the field and with role=alert.
|
|
315
|
+
- Prove it: run `npx @axe-core/cli http://127.0.0.1:3000` or Playwright with @axe-core/playwright; fix every serious/critical finding and record the run with verify. Tab through the main flow in the browser tool.
|
|
316
|
+
'''),
|
|
317
|
+
_s('web-performance', 'Web performance and Core Web Vitals', 'Measure and improve LCP, INP, CLS, bundle size and server latency with real numbers before and after.',
|
|
318
|
+
['performance', 'slow', 'lighthouse', 'core web vitals', 'lcp', 'bundle size', 'latency', 'optimize', 'optimise', 'speed up'], '''
|
|
319
|
+
- Expects Vault: nothing by default; a Lighthouse CI or CrUX API key only when the project reports to a hosted dashboard.
|
|
320
|
+
- Measure before touching code: Lighthouse (`npx lighthouse http://127.0.0.1:3000 --preset=desktop --output=json --quiet`), bundle analysis (`ANALYZE=1 next build` or `npx vite-bundle-visualizer`), server timings from logs. Write the baseline numbers down.
|
|
321
|
+
- Fix in order of impact: render-blocking requests, oversized images (next/image, AVIF/WebP, explicit width/height), unused JavaScript (dynamic import, drop heavy deps), waterfalls (parallel fetches, server components), layout shift (reserved space, font-display swap), long tasks (move work off the main thread).
|
|
322
|
+
- Backend: add indexes for slow queries (EXPLAIN ANALYZE), cache idempotent reads, paginate, avoid N+1 with joins or dataloaders.
|
|
323
|
+
- Re-measure after each change and report before/after; never claim "faster" without numbers. Keep a performance budget in the repo (bundle size or Lighthouse score) when the project has CI.
|
|
324
|
+
'''),
|
|
325
|
+
_s('api-design-openapi', 'API design and OpenAPI contracts', 'Design REST or GraphQL APIs with a written contract, versioning, auth, pagination, errors and generated clients.',
|
|
326
|
+
['openapi', 'swagger', 'api design', 'rest api', 'graphql', 'webhook', 'sdk', 'api contract', 'public api'], '''
|
|
327
|
+
- Expects Vault: DATABASE_URL for the backing store and any third-party API key the service proxies; webhook signing secrets (for example STRIPE_WEBHOOK_SECRET) when receiving webhooks.
|
|
328
|
+
- Contract first: write or update openapi.yaml (or the GraphQL schema) before handlers. Resource nouns, plural paths, consistent casing, ISO-8601 timestamps, cursor pagination, idempotency keys on unsafe POSTs.
|
|
329
|
+
- Errors as a stable shape ({error:{code,message,details}}) with correct status codes; never leak stack traces. Validate every input at the edge (zod / pydantic) and return field-level errors.
|
|
330
|
+
- Auth: bearer tokens or API keys hashed at rest, scopes per endpoint, rate limits with Retry-After. Webhooks are signed (HMAC) and retried with backoff; document the signature check.
|
|
331
|
+
- Version with a path or header from day one (/v1). Generate the client or types from the contract (openapi-typescript, orval) instead of hand-writing them, and add a contract test that the live routes match the spec.
|
|
332
|
+
'''),
|
|
333
|
+
_s('database-performance', 'Database design and performance', 'Schema design, migrations, indexing, query tuning and safe data changes for Postgres, MySQL and SQLite.',
|
|
334
|
+
['schema', 'index', 'slow query', 'query plan', 'explain analyze', 'normalize', 'postgres tuning', 'deadlock', 'database design'], '''
|
|
335
|
+
- Expects Vault: DATABASE_URL (pooled) and DIRECT_URL / DATABASE_URL_UNPOOLED for migrations. Never run against production without approval.
|
|
336
|
+
- Model first: primary keys, foreign keys with ON DELETE rules, NOT NULL and CHECK constraints, unique indexes for business keys, created_at/updated_at. Prefer bigint or uuid ids consistently.
|
|
337
|
+
- Every schema change is a reversible migration file (Prisma, Drizzle, Alembic, Knex); never edit the database by hand. Large tables: add indexes CONCURRENTLY, backfill in batches, avoid locking rewrites.
|
|
338
|
+
- Tune with evidence: `EXPLAIN (ANALYZE, BUFFERS)` the slow statement, add the covering or composite index the plan asks for, rewrite N+1 loops as joins or IN lists, paginate with keyset cursors.
|
|
339
|
+
- Data safety: wrap multi-statement changes in transactions, test migrations against a copy with representative row counts, and never run destructive SQL (DROP, TRUNCATE, DELETE without WHERE) without an explicit approval and a backup.
|
|
340
|
+
'''),
|
|
341
|
+
_s('desktop-electron-tauri', 'Desktop apps (Electron and Tauri)', 'Build cross-platform desktop apps with a web UI: windows, menus, native file access, auto-update and signed installers.',
|
|
342
|
+
['electron', 'tauri', 'desktop app', 'menu bar app', 'tray', 'native app', 'installer', 'dmg', 'msi'], '''
|
|
343
|
+
- Expects Vault: nothing by default; APPLE_ID / APPLE_APP_SPECIFIC_PASSWORD or WINDOWS_CERT_PASSWORD only for signed release builds, TAURI_SIGNING_PRIVATE_KEY for the updater.
|
|
344
|
+
- Prefer Tauri 2 for small, secure binaries (Rust shell, web frontend); use Electron when Node APIs or Chromium parity are required. Keep all privileged work in the main/Rust side behind a narrow IPC (contextIsolation on, nodeIntegration off; Tauri capabilities scoped per window).
|
|
345
|
+
- Implement the desktop basics: native menu with shortcuts, window state persistence, file open/save dialogs, deep links, tray when the app runs in the background, and graceful quit.
|
|
346
|
+
- Build targets and signing config live in the repo (tauri.conf.json or electron-builder.yml); never commit certificates. Auto-update through the framework updater with a signed manifest.
|
|
347
|
+
- Verify: run the app in dev (`npm run tauri dev` / `npm run dev`), exercise the IPC paths, and produce a build (`tauri build` or `electron-builder --dir`) to prove it packages.
|
|
348
|
+
'''),
|
|
349
|
+
_s('browser-extension', 'Browser extensions (Manifest V3)', 'Build Chrome, Edge and Firefox extensions: service worker, content scripts, popup/options UI, storage and permissions.',
|
|
350
|
+
['chrome extension', 'browser extension', 'manifest v3', 'content script', 'firefox addon', 'web extension'], '''
|
|
351
|
+
- Expects Vault: nothing by default; CHROME_CLIENT_ID / CHROME_CLIENT_SECRET / CHROME_REFRESH_TOKEN or WEB_EXT_API_KEY only when publishing to a store.
|
|
352
|
+
- Manifest V3: background service worker (no persistent page), declarativeNetRequest instead of blocking webRequest, least-privilege permissions with optional_permissions requested on demand, host_permissions listed explicitly.
|
|
353
|
+
- Structure: popup and options pages as small React/Vite builds, content scripts isolated and message-based (chrome.runtime.sendMessage), shared types for messages, chrome.storage.sync for settings.
|
|
354
|
+
- Cross-browser: use the webextension-polyfill or `browser.*` namespace, and keep a firefox-specific manifest override (browser_specific_settings) when needed.
|
|
355
|
+
- Verify by loading the unpacked build (`npm run build`, then chrome://extensions) and exercising popup, content script and storage; run `npx web-ext lint` for Firefox compatibility.
|
|
356
|
+
'''),
|
|
357
|
+
_s('game-dev', 'Game development (web and engine)', 'Build games with a real loop: Phaser/PixiJS/Three.js on the web, Godot or Unity when an engine project exists.',
|
|
358
|
+
['game', 'phaser', 'pixijs', 'three.js', 'godot', 'unity', 'sprite', 'physics', 'game loop', '2d game', '3d game'], '''
|
|
359
|
+
- Expects Vault: nothing by default; a multiplayer backend key (for example SUPABASE or ABLY_API_KEY) only when the game is online.
|
|
360
|
+
- Match the repo: Godot (.tscn/.gd), Unity (.cs, Assets/), or web (Phaser 3 for 2D, Three.js/R3F for 3D, PixiJS for rendering). Do not introduce a second engine.
|
|
361
|
+
- Core loop first: input, update with a fixed timestep, render, win/lose state, restart. Then feel: easing, hit feedback, sound hooks, particles. Keep game state in a plain model separate from rendering.
|
|
362
|
+
- Assets: generate placeholder sprites procedurally or with the image tool and keep them in assets/ with a manifest; never hotlink.
|
|
363
|
+
- Performance: object pooling, sprite atlases, capped delta time, requestAnimationFrame. Verify in the browser tool at 60 fps on desktop and touch controls on a phone viewport; for engines, run the headless export or test scene command.
|
|
364
|
+
'''),
|
|
365
|
+
_s('cli-tooling', 'CLI and developer tooling', 'Build command-line tools and dev scripts: argument parsing, help text, exit codes, config, colours and distribution.',
|
|
366
|
+
['cli', 'command line', 'command-line', 'terminal tool', 'npx', 'developer tool', 'codemod', 'generator'], '''
|
|
367
|
+
- Expects Vault: nothing by default; NPM_TOKEN or PYPI_TOKEN only when publishing a release.
|
|
368
|
+
- Use a real parser (commander/clipanion/oclif for Node, typer/click for Python, cobra for Go). Every command has --help with examples, --json for machine output, --dry-run for anything that writes, and meaningful exit codes (0 ok, 1 failure, 2 usage).
|
|
369
|
+
- Respect the environment: NO_COLOR, CI (no spinners), XDG config paths, stdin piping, and never prompt when stdout is not a TTY.
|
|
370
|
+
- Fast start-up: lazy imports, no network at boot, cached version checks. Errors say what failed and what to do next.
|
|
371
|
+
- Distribution: bin entry in package.json or pyproject scripts, shebang, executable bit; test with `npm pack && npx ./*.tgz --help` or `pipx run .`. Add a smoke test that runs the binary.
|
|
372
|
+
'''),
|
|
373
|
+
_s('docs-technical-writing', 'Documentation and technical writing', 'Write README, guides, API reference, ADRs and changelogs that match the code and can be verified.',
|
|
374
|
+
['documentation', 'docs', 'readme', 'guide', 'tutorial', 'changelog', 'api reference', 'docusaurus', 'mkdocs', 'write up'], '''
|
|
375
|
+
- Expects Vault: nothing by default; a docs host token (VERCEL_TOKEN, CLOUDFLARE_API_TOKEN, ALGOLIA_API_KEY for search) only when publishing.
|
|
376
|
+
- Start from the reader: a README answers what it is, who it is for, install, first success in 5 minutes, configuration, troubleshooting, licence. One task per guide page.
|
|
377
|
+
- Every command and code sample must run: copy it from the repo or run it, and paste real output. Reference docs are generated from source where possible (typedoc, sphinx-autodoc, openapi).
|
|
378
|
+
- Structure with Diataxis: tutorials, how-to guides, reference, explanation. Use consistent headings, short sentences, tables for options, admonitions sparingly.
|
|
379
|
+
- Keep docs in the repo (docs/ with Docusaurus, MkDocs or Nextra when a site is wanted), add a link check (`npx markdown-link-check`) and a build (`mkdocs build --strict`) to CI, and update CHANGELOG.md with user-facing changes.
|
|
380
|
+
'''),
|
|
381
|
+
_s('analytics-dbt-bi', 'Analytics engineering (dbt, SQL, BI)', 'Model warehouse data with dbt or SQL, define metrics once, test them and ship dashboards people trust.',
|
|
382
|
+
['dbt', 'warehouse', 'bigquery', 'snowflake', 'redshift', 'metrics layer', 'dashboard', 'looker', 'metabase', 'kpi', 'semantic layer'], '''
|
|
383
|
+
- Expects Vault: warehouse credentials such as DATABASE_URL, BIGQUERY_CREDENTIALS, SNOWFLAKE_ACCOUNT / SNOWFLAKE_USER / SNOWFLAKE_PASSWORD; BI tokens (METABASE_API_KEY, LOOKER_CLIENT_ID) when publishing dashboards.
|
|
384
|
+
- Layer models: staging (rename, cast, one per source table), intermediate (joins, business logic), marts (facts and dimensions). One definition per metric with its grain stated in the model doc.
|
|
385
|
+
- Tests on every model: not_null and unique on keys, accepted_values on enums, relationships for foreign keys, plus a freshness check on sources. `dbt build` must pass before a dashboard reads the model.
|
|
386
|
+
- SQL that scales: incremental models for event tables, partition and cluster keys, no SELECT *, CTEs named for what they compute.
|
|
387
|
+
- Dashboards show the question, the number, the trend and the definition link; defaults to the last complete period. Verify numbers against a raw query before publishing and record the check with verify.
|
|
388
|
+
'''),
|
|
389
|
+
_s('llm-evals', 'LLM evaluation and prompt engineering', 'Build evaluation sets, graders and regression gates for prompts, agents and RAG; iterate on prompts with evidence.',
|
|
390
|
+
['eval', 'evals', 'evaluation set', 'prompt engineering', 'system prompt', 'hallucination', 'llm quality', 'grader', 'golden set'], '''
|
|
391
|
+
- Expects Vault: OPENAI_API_KEY, ANTHROPIC_API_KEY or the model gateway key the app uses; BRAINTRUST_API_KEY or LANGSMITH_API_KEY when a hosted eval tracker is used.
|
|
392
|
+
- Start with a dataset: 30 to 200 real or realistic cases in JSONL with input, expected behaviour and tags. Hold out a slice for regression. Store it in evals/ in the repo.
|
|
393
|
+
- Graders: exact or structured checks where possible (JSON schema, contains, numeric tolerance), rubric-based model grading only for open text, with the rubric written down. Report per-tag pass rates, cost and latency, not a single number.
|
|
394
|
+
- Prompt changes are experiments: change one thing, run the whole set, compare against the last run, keep the prompt and results versioned. Use promptfoo, Braintrust, LangSmith or a plain script; wire the run into CI with a threshold.
|
|
395
|
+
- Production: log inputs/outputs with ids, sample for review, and add guardrails (schema validation, retries with repair, refusal handling). Never claim quality without an eval run and its numbers.
|
|
396
|
+
'''),
|
|
397
|
+
_s('search-recsys', 'Search and recommendations', 'Build full-text, vector and hybrid search with ranking, filters, synonyms and offline relevance checks.',
|
|
398
|
+
['full text search', 'vector search', 'semantic search', 'embeddings', 'ranking', 'recommendation', 'recommend', 'typesense', 'meilisearch', 'elasticsearch', 'pgvector', 'algolia'], '''
|
|
399
|
+
- Expects Vault: DATABASE_URL for pgvector / tsvector; MEILI_MASTER_KEY, TYPESENSE_API_KEY, ELASTIC_CLOUD_ID / ELASTIC_API_KEY, ALGOLIA_APP_ID / ALGOLIA_ADMIN_KEY or PINECONE_API_KEY for hosted engines; an embeddings key (OPENAI_API_KEY) for semantic search.
|
|
400
|
+
- Choose by scale: Postgres tsvector + pgvector for most apps, Meilisearch/Typesense for instant search UX, Elasticsearch/OpenSearch for large or analytical corpora, hosted (Algolia, Pinecone) when the project already pays for one.
|
|
401
|
+
- Index design: analyzers for language and stemming, synonyms, typo tolerance, fields with weights, facets for filters, and a document id that lets you reindex safely. Keep the indexing job idempotent and incremental.
|
|
402
|
+
- Hybrid ranking: combine BM25 and embedding scores (reciprocal rank fusion), apply business boosts (recency, popularity) last, and paginate with cursors.
|
|
403
|
+
- Relevance is measured: build a small judged set of queries with expected results and compute recall@k / nDCG before and after changes; log zero-result queries. Recommendations start with co-occurrence or embeddings over user events, with an explanation ("because you viewed X").
|
|
404
|
+
'''),
|
|
405
|
+
_s('realtime-streaming', 'Realtime and streaming systems', 'WebSockets, SSE, presence, pub/sub, queues and event streams that stay correct under reconnects and load.',
|
|
406
|
+
['websocket', 'realtime', 'real-time', 'live updates', 'presence', 'pub/sub', 'kafka', 'redis streams', 'server-sent events', 'collaborative', 'multiplayer', 'event stream'], '''
|
|
407
|
+
- Expects Vault: REDIS_URL, KAFKA_BROKERS with credentials, or the realtime provider key (ABLY_API_KEY, PUSHER_SECRET, LIVEBLOCKS_SECRET_KEY, SUPABASE service role) when one is used.
|
|
408
|
+
- Pick the transport by need: SSE for server-to-client updates, WebSockets for bidirectional or presence, a queue (Redis Streams, SQS, Kafka) for work that must survive restarts. Serverless hosts need a managed realtime layer (Supabase Realtime, Ably, Pusher, Liveblocks) instead of long-lived sockets.
|
|
409
|
+
- Protocol: versioned message types, ids and timestamps on every event, heartbeat/ping, exponential-backoff reconnect with resume from last id, idempotent handlers so duplicates are harmless.
|
|
410
|
+
- State: authoritative on the server; clients render optimistic updates and reconcile. For collaboration use a CRDT (Yjs, Automerge) instead of hand-rolled merging.
|
|
411
|
+
- Verify with two clients in the browser tool or a small script: message arrives within a second, reconnect replays missed events, and the server survives a client vanishing mid-stream. Add backpressure (bounded buffers) and per-connection limits.
|
|
412
|
+
'''),
|
|
413
|
+
_s('design-engineering-motion', 'Design engineering: systems, motion and polish', 'Turn design intent into a coherent system: tokens, components, typography, motion and the small details that make a product feel finished.',
|
|
414
|
+
['design system', 'design tokens', 'motion', 'micro-interaction', 'polish', 'storybook', 'framer motion', 'animation', 'typography', 'theme', 'dark mode'], '''
|
|
415
|
+
- Expects Vault: nothing by default; CHROMATIC_PROJECT_TOKEN only when visual regression runs in CI.
|
|
416
|
+
- Tokens before components: colour, spacing, radius, type scale and shadows as CSS variables (or Tailwind theme) with semantic names (--surface, --text-muted), light and dark values, documented in one file.
|
|
417
|
+
- Components in Storybook (or an internal /design route) with every state: default, hover, focus, active, disabled, loading, error, empty. Consistency beats novelty; reuse the existing primitives.
|
|
418
|
+
- Motion with purpose: 120 to 240 ms for feedback, 240 to 400 ms for layout changes, standard easing (ease-out for enter, ease-in for exit), spring for drag, nothing loops forever. Everything respects prefers-reduced-motion.
|
|
419
|
+
- Finish pass: alignment to the grid, consistent icon sizes, tabular numerals for data, real empty and error states, focus rings, 44 px touch targets. Check in the browser tool at 360, 768 and 1280 px and in dark mode before finishing.
|
|
420
|
+
'''),
|
|
421
|
+
_s('legacy-migration', 'Migrations and modernisation', 'Upgrade frameworks and languages, replace libraries, move between platforms and databases safely in reviewable steps.',
|
|
422
|
+
['migrate', 'upgrade', 'modernize', 'modernise', 'legacy', 'port to', 'convert to', 'move from', 'deprecated', 'breaking changes', 'rewrite'], '''
|
|
423
|
+
- Expects Vault: DATABASE_URL (and the target database URL) when data moves; otherwise nothing by default.
|
|
424
|
+
- Characterise before changing: inventory versions, deprecations, test coverage and the entry points; write a short migration plan with phases that each leave the app working (strangler pattern), and get it approved.
|
|
425
|
+
- One axis at a time: upgrade the runtime, then the framework, then libraries; use official codemods (`npx @next/codemod`, `npx react-codemod`, `pyupgrade`, `rector`) before hand edits. Keep commits small and reversible.
|
|
426
|
+
- Add characterisation tests around behaviour you must preserve before touching it; run the full suite after every phase. Database moves use dual writes or a backfill plus a cutover switch, never a big-bang copy.
|
|
427
|
+
- Finish each phase with the build, tests and a smoke run of the main flow; document what changed, what is deprecated next and the rollback for this phase.
|
|
428
|
+
'''),
|
|
429
|
+
_s('growth-experiments', 'Growth engineering: experiments, SEO and funnels', 'Instrument funnels, run A/B tests correctly, ship SEO and sharing basics, and tie changes to measured outcomes.',
|
|
430
|
+
['a/b test', 'ab test', 'experiment', 'feature flag', 'conversion', 'funnel', 'seo', 'onboarding', 'signup flow', 'retention', 'growth', 'referral'], '''
|
|
431
|
+
- Expects Vault: NEXT_PUBLIC_POSTHOG_KEY / POSTHOG_API_KEY, GA4 measurement id, or SEGMENT_WRITE_KEY for events; RESEND_API_KEY for lifecycle email.
|
|
432
|
+
- Measure first: define the funnel events (viewed, started, completed) with a shared naming scheme and send them through the existing analytics (PostHog, GA4, Segment) with user and session ids; verify events arrive before building anything on them.
|
|
433
|
+
- Experiments: feature flags with deterministic bucketing, a written hypothesis and primary metric, minimum sample size estimated up front, and exposure logged once per user. Never peek-and-stop; report lift with confidence intervals.
|
|
434
|
+
- SEO and sharing: unique title and meta description per page, canonical URLs, Open Graph and Twitter cards with a real image, sitemap.xml and robots.txt, structured data where it applies, fast LCP. Check with `npx lighthouse --only-categories=seo`.
|
|
435
|
+
- Onboarding and activation: remove steps before adding features, show progress, default sensible values, and send the one email that matters. Tie every change to a number in the summary.
|
|
436
|
+
'''),
|
|
437
|
+
_s('web3-solidity', 'Web3 and smart contracts', 'Write and test Solidity contracts with Foundry or Hardhat, wire a wallet-connected frontend, and treat every deployment as irreversible.',
|
|
438
|
+
['solidity', 'smart contract', 'web3', 'ethereum', 'evm', 'erc20', 'erc721', 'nft', 'wallet', 'wagmi', 'viem', 'hardhat', 'foundry', 'defi', 'onchain', 'on-chain'], '''
|
|
439
|
+
- Expects Vault: a testnet RPC URL (SEPOLIA_RPC_URL or ALCHEMY_API_KEY) and ETHERSCAN_API_KEY for verification. A DEPLOYER_PRIVATE_KEY must only ever be a throwaway test key; never request or store a mainnet key.
|
|
440
|
+
- Use Foundry (forge test, fuzzing, gas reports) or the existing Hardhat setup; pin the compiler, use OpenZeppelin for standards, Checks-Effects-Interactions, reentrancy guards, explicit access control, and events for every state change.
|
|
441
|
+
- Tests cover happy paths, reverts with custom errors, fuzzed inputs and invariants; run `forge test -vvv` and `slither .` when available and fix findings before anything else.
|
|
442
|
+
- Frontend: wagmi + viem (or ethers) with typed ABIs generated from the artifacts, chain switching, pending/confirmed/failed transaction states, and simulated calls before sending.
|
|
443
|
+
- Deploy only to a local or test network (anvil, Sepolia) without explicit approval; mainnet deploys and upgrades are irreversible and need the user's go-ahead, a verified source on the explorer and a written key-management plan.
|
|
444
|
+
'''),
|
|
445
|
+
_s('i18n-l10n', 'Internationalisation and localisation', 'Add locale support the right way: message catalogs, plurals, dates and currencies, RTL layouts and translation workflow.',
|
|
446
|
+
['i18n', 'l10n', 'internationalization', 'internationalisation', 'localization', 'localisation', 'translate', 'translations', 'multi-language', 'multilingual', 'rtl', 'locale'], '''
|
|
447
|
+
- Expects Vault: nothing by default; a translation platform token (CROWDIN_TOKEN, LOKALISE_API_TOKEN, DEEPL_API_KEY) only when syncing translations.
|
|
448
|
+
- Use the framework i18n (next-intl / react-intl / i18next, Django or Rails built-ins): no string concatenation, ICU messages for plurals and gender, Intl APIs for dates, numbers and currencies, locale in the URL or a cookie with a sensible default.
|
|
449
|
+
- Extract every user-visible string into the catalog with stable keys; keep the source locale complete and add a check that other locales have no missing keys (`i18next-parser`, `formatjs extract`).
|
|
450
|
+
- Layout: logical CSS properties (margin-inline), dir=rtl support, text expansion room (German is ~30% longer), no text in images, locale-aware sorting and search.
|
|
451
|
+
- Verify by switching to at least two locales in the browser tool (one RTL when supported), checking plural forms and a formatted date and price.
|
|
452
|
+
'''),
|
|
453
|
+
]
|
|
454
|
+
|
|
455
|
+
PACK.append(_s('image-generation', 'Generate visual assets', 'Create original hero imagery, product shots, illustrations and backgrounds with the built-in image tool, then integrate and verify them.',
|
|
456
|
+
['generate image', 'generate images', 'hero image', 'illustration', 'visual assets', 'image generation', 'background image', 'product shots', 'art direction', 'brand visuals', 'moodboard'], """
|
|
457
|
+
Expects Vault: none. The image service is set up by the app operator on the server and is included with the task at no extra credits; never ask the user for a key and never put one in generated code.
|
|
458
|
+
Use the generate_image tool (Kimi: mcp__mlai__generate_image). It saves actual assets under public/generated/ and returns a path, URL, model and measured cost when available.
|
|
459
|
+
1. Art direction first. Inspect the UI, then write one style line for the whole project (palette with hex values, lighting, lens or render style, texture, mood) and a shot list: what each image is for, where it goes and its aspect ratio. Reuse the style line in every prompt so the set reads as one brand.
|
|
460
|
+
2. Generate only when original raster artwork adds value (hero, product, people, places, backgrounds, deck covers). Use CSS, SVG and the established icon library for controls, charts, diagrams, patterns and simple icons.
|
|
461
|
+
3. Write each prompt as a self-contained brief: subject, composition, camera or render style, lighting, palette, aspect ratio and negative space for HTML headings. Add "no text, no letters, no logos, no watermark". Do not bake UI labels or buttons into images. Never send credentials, personal data or private source code, and never depict real people by name.
|
|
462
|
+
4. Call generate_image {prompt, filename, aspect_ratio}. Use at most four provider attempts per run, one image per call, so spend them on the images that matter most. Reuse existing assets and do not retry a timeout blindly. Failed generation is not a saved asset: fall back to CSS or SVG art and carry on.
|
|
463
|
+
5. Use the returned real path/URL, preserve its extension, set meaningful alt text, object-fit and responsive dimensions. The provider may return a different raster format than requested.
|
|
464
|
+
6. Verify: run the app and inspect mobile/desktop crops, contrast of text over imagery and page behavior with the browser. Generated artwork is not proof that the finished UI works.
|
|
465
|
+
"""))
|
|
466
|
+
|
|
467
|
+
PACK.append(_s('frontend-design', 'Frontend design lead', 'Art-direct and build interfaces that look designed: a short brief, one token system, real copy and imagery, every state, checked in the browser.',
|
|
468
|
+
['redesign', 'landing page', 'website', 'web page', 'hero section', 'look and feel', 'ui design', 'web design', 'visual design', 'beautiful', 'modern ui', 'make it look', 'polish the ui'], """
|
|
469
|
+
Expects Vault: nothing. Images come from the built-in generate_image tool, which is included with the task at no extra credits.
|
|
470
|
+
The Frontend engineer leads design for every screen, whichever engineer writes the rest. Work in this order.
|
|
471
|
+
1. Brief (five lines, in the plan or first message): who it is for, the one job of each screen, the mood in three words, the chosen direction, and the one thing that makes it memorable. When the project has a selected design direction or an existing design system, follow it and say so. Otherwise pick a direction that fits the subject (editorial, product-led, playful, technical, luxury, brutalist) instead of the default template look: no purple-on-white gradient hero, no three identical feature cards, no centred everything.
|
|
472
|
+
2. Tokens before screens, in one file (CSS variables or the Tailwind theme): one accent plus neutrals with semantic names (--bg, --surface, --text, --muted, --accent, --border) and light and dark values when the product has both; one display face and one text face (self-hosted or next/font, two families at most) on a five or six step scale; a 4 or 8 px spacing scale; two radii; two shadow levels. Text contrast is at least 4.5:1. No one-off hex values or font sizes after this point.
|
|
473
|
+
3. Composition: one focal point per screen and a clear reading order. Use a consistent grid and generous whitespace. On long pages vary the rhythm (full-bleed hero, split, grid, quote, stat band, call to action) so no two adjacent sections share a layout. Dense app screens (tables, dashboards) favour alignment, tabular numerals and quiet chrome over decoration.
|
|
474
|
+
4. Real content: write specific copy for this product (names, numbers, benefits, a clear primary action). No lorem ipsum, no "Welcome to our website".
|
|
475
|
+
5. Imagery: where a real product would show pictures (hero, product, people, places, section backgrounds), call generate_image {prompt, filename, aspect_ratio}. Four images per run, so choose the ones that carry the page. Keep one art direction (same palette, lighting and style in every prompt), no text inside images, alt text and explicit sizes on every img. Icons come from the icon library already in the repo (lucide by default); charts, patterns, gradients and decorative shapes are CSS or SVG. Never ship grey boxes, broken image links or hotlinked stock photos. If the image tool is unavailable or the limit is reached, use CSS or SVG art and carry on.
|
|
476
|
+
6. States and interaction: hover, focus-visible, active and disabled on every control; loading skeletons that match the final layout; empty views with a next step; errors with retry; inline form validation that keeps what the user typed; 44 px touch targets.
|
|
477
|
+
7. Motion: 120 to 240 ms for feedback and 240 to 400 ms for layout, transform and opacity only, ease-out to enter and ease-in to exit, at most one signature moment per page, and a prefers-reduced-motion fallback.
|
|
478
|
+
8. Responsive: build phone first. No sideways scroll at 360 px, navigation that collapses to a real menu, type that scales with clamp(), images that crop well at every width.
|
|
479
|
+
9. Finish pass in the browser tool at 360, 768 and 1280 px (and in dark mode when it exists): alignment to the grid, consistent spacing and icon sizes, no orphaned heading words, no clipped or overlapping text, contrast of text over images, focus order. Fix what you see, then say in the summary what direction was chosen and what was checked.
|
|
480
|
+
Native mobile, desktop and game interfaces follow the same order with the platform's own toolkit and conventions (safe areas, system fonts, navigation patterns) instead of web CSS.
|
|
481
|
+
"""))
|
|
482
|
+
|
|
483
|
+
PACK.append(_s('presentations', 'Presentations and PDF documents', 'Create editable slide decks (decks/*.deck.json) and designed PDF-ready documents that the app renders, edits and exports to PDF and PowerPoint.',
|
|
484
|
+
['presentation', 'slides', 'slide deck', 'deck', 'pitch deck', 'keynote', 'powerpoint', 'pptx', 'pdf', 'report', 'one pager', 'one-pager', 'brochure', 'investor deck', 'sales deck'], """
|
|
485
|
+
Expects Vault: none.
|
|
486
|
+
Decks: write decks/<name>.deck.json. The app's file viewer shows it as 16:9 slides, lets the user edit text inline, reorder and add slides, present full screen and export PDF or PowerPoint. Do not build a separate slide web app unless asked.
|
|
487
|
+
Schema (version 1):
|
|
488
|
+
{"version":1,"title":"...","theme":{"background":"#0b0b10","surface":"#16161d","text":"#f5f5f7","muted":"#a1a1aa","accent":"#8b5cf6","accent2":"#f59e0b","font":"Inter"},
|
|
489
|
+
"slides":[
|
|
490
|
+
{"layout":"cover","kicker":"...","title":"...","subtitle":"...","image":"public/generated/cover.png"},
|
|
491
|
+
{"layout":"section","kicker":"02","title":"...","subtitle":"..."},
|
|
492
|
+
{"layout":"bullets","title":"...","bullets":["...","..."],"image":"optional path"},
|
|
493
|
+
{"layout":"split","title":"...","body":"...","bullets":["..."],"image":"public/generated/x.png","imageSide":"right"},
|
|
494
|
+
{"layout":"image","title":"...","caption":"...","image":"public/generated/full.png"},
|
|
495
|
+
{"layout":"stats","title":"...","stats":[{"value":"3.2x","label":"..."}]},
|
|
496
|
+
{"layout":"columns","title":"...","columns":[{"title":"...","body":"..."}]},
|
|
497
|
+
{"layout":"quote","quote":"...","author":"..."},
|
|
498
|
+
{"layout":"closing","title":"...","subtitle":"..."}],
|
|
499
|
+
every slide may add "notes" (speaker notes) and "background" (an image path for a full-bleed backdrop)}
|
|
500
|
+
Rules: one idea per slide, titles under 8 words, at most 5 bullets of under 14 words, numbers in stats slides, a cover and a closing slide. Image paths are workspace-relative (public/generated/...). Use generate_image for the cover and the key slides (four images per run, included at no extra credits) in one shared style, keep text out of generated images, and let layout, type and colour carry the rest. Validate the JSON (python3 -m json.tool) before finishing and tell the user to open it in Files to edit and export.
|
|
501
|
+
Documents and PDFs: write reports/<name>.html as a self-contained, print-ready page (A4 or Letter, @page margins, page-break-before on sections, embedded CSS, images by relative path). The viewer previews it and exports PDF. Markdown (.md) files also preview and export to PDF. When a real .pdf file must exist in the repository, render the HTML with an available headless browser (for example Playwright page.pdf with landscape for slides) and check the page count and that the file opens.
|
|
502
|
+
"""))
|
|
503
|
+
|
|
504
|
+
PACK.append(_s('deploy-vercel', 'Deploy previews and ship to production', 'Deploy the workspace to the connected host (Vercel, Netlify, Cloudflare Pages or custom commands), verify the preview, fix failed builds and request promotion to production.',
|
|
505
|
+
['deploy', 'preview url', 'ship it', 'go live', 'production', 'vercel', 'netlify', 'cloudflare pages', 'publish the app', 'staging'], """
|
|
506
|
+
Expects Vault: nothing. The deploy token lives on the server; you never see it and must never ask for it.
|
|
507
|
+
1. Call the deploy tool (Kimi: mcp__mlai__deploy) with {action: preview}. Depending on the host the user connected, it uploads the tracked files (Vercel), builds the site here and uploads the output folder (Netlify, Cloudflare Pages), or runs the user's own preview command (custom script). Local secret files and node_modules are never uploaded. It returns a deployment id and, when ready, a URL.
|
|
508
|
+
2. Call {action: status, deployment} until the state is READY or ERROR. Builds usually take one to three minutes. For static hosts a build error is returned right away with the last build lines: fix the build (npm run build must pass locally) before trying again.
|
|
509
|
+
3. READY: open the preview URL with the browser tool, check the main page and one key flow at mobile and desktop widths, then report the link.
|
|
510
|
+
4. ERROR: call {action: logs, deployment}. Common causes: a missing environment variable (tell the user the exact name to add in Vault with the Preview scope), the wrong Node version (set engines.node in package.json), a build-time import of a runtime-only secret, or a case-sensitive import path. Fix and deploy a new preview.
|
|
511
|
+
5. Production: only when the user asked for it, call {action: request_promotion, deployment, reason}. The user sees the preview, checks and rollback plan and decides. Never run vercel, netlify, wrangler, fly or railway CLIs with --prod, promote or rollback yourself; those commands are blocked.
|
|
512
|
+
"""))
|
|
513
|
+
|
|
514
|
+
PACK.append(_s('rollback-triage', 'Investigate a rolled-back release', 'After production was rolled back, find what broke in the bad build and prepare a safe fix with a fresh preview.',
|
|
515
|
+
['rolled back', 'rollback', 'production broke', 'revert release', 'bad deploy', 'incident'], """
|
|
516
|
+
Expects Vault: nothing.
|
|
517
|
+
1. Read the task: it names the bad deployment, the commit and the last build log lines. Production is already safe on the previous build, so work carefully rather than fast.
|
|
518
|
+
2. Compare the bad commit with the previous good one (git log / git diff) and list the changes that could explain the failure.
|
|
519
|
+
3. Reproduce locally where possible (install, build, run the failing route) and confirm the cause before editing.
|
|
520
|
+
4. Fix the smallest thing that explains the failure and add a test that would have caught it.
|
|
521
|
+
5. Deploy a preview with the deploy tool, verify it in the browser, and report the cause, the fix, the test and the preview link. Request promotion only if the user asks.
|
|
522
|
+
"""))
|
|
523
|
+
|
|
524
|
+
PACK.append(_s('incident-triage', 'Triage a production alert', 'Turn a production alert (uptime, error, Sentry issue, log drain) into a reproduced, root-caused fix with a regression test.',
|
|
525
|
+
['alert', 'incident', 'production error', 'sentry', 'outage', 'down', '500', 'error spike', 'triage'], """
|
|
526
|
+
Expects Vault: nothing (SENTRY_AUTH_TOKEN helps when the alert came from Sentry).
|
|
527
|
+
1. Read the alert in the task: title, count, URL or route, status code, stack, release. Note when it started and whether a release went out just before it.
|
|
528
|
+
2. Reproduce before you fix. Install, build, and hit the failing route or run the failing code path locally, or write a failing test from the stack trace. If you cannot reproduce it, say exactly what you tried and what is missing; do not guess a fix.
|
|
529
|
+
3. Find the root cause: read the code at the top stack frame, then `git log -p` for the files involved since the last good release. Explain the cause in one or two sentences.
|
|
530
|
+
4. Fix the cause, not the symptom. Do not swallow the exception, widen a try/catch or delete the check that raised it.
|
|
531
|
+
5. Add a regression test that fails before the fix and passes after it. Run the full test suite and the build.
|
|
532
|
+
6. Open a pull request titled "Fix: <alert title>" with the cause, the fix, the test and how to verify in production. Never deploy or promote yourself; a person decides.
|
|
533
|
+
"""))
|