AI Agent Workflow

Use when the user asks to initialize, analyze codebase, or generate the repository's primary agent context file. This skill should be used at the start of a new project or when the main agent context file is missing.

Use when the user asks to fix a bug, investigate a broken behavior, or trace an error. Follows reproduce → isolate root cause → minimal fix → regression prevention discipline. Do not use for feature changes or refactoring.

Use when the user asks to refactor, restructure, clean up, or improve the internal design of code without changing its behavior. Requires a clear baseline, explicit motivation, and behavior parity validation. Do not use for bug fixes, feature additions, or behavior changes — those must be separate tasks.

Use when designing new tables or collections, choosing between normalization approaches, planning indexes, writing migration scripts, modeling many-to-many or hierarchical data, or deciding on soft delete vs hard delete. Skip when writing queries against an already-defined schema with no design decisions.

Perform a focused, high-confidence review of a pull request, branch, commit range, or working-tree diff. Prioritize merge-blocking defects that AI-generated changes commonly introduce, with or without PR context, and avoid broad speculative review or generic best-practice advice.

Use when the user asks to update a spec after implementation. Reconciles the spec with the current codebase and proposes business-level deltas when needed.

Use when designing new API endpoints, reviewing API contracts, aligning FE/BE on schema, adding versioning strategy, defining error response structure, or any task involving API interface decisions. Skip when implementing existing well-defined API specs with no design decisions needed.

Use when the user asks to create a detailed implementation specification or when an approved design decision manifest must be converted into the durable source of truth for implementation and verification. Creates docs/ai/features/specs/{feature}.md with approved intent, codebase evidence, concrete technical design, implementation mapping, acceptance criteria, and verification strategy.

Create or resume a local interactive design review for a feature, collect high-level human decisions through the bundled local runner, and persist an approved decision manifest before detailed spec creation. Use before create-spec for new features or material user-visible changes that need human choices about scope, behavior, business rules, compatibility, or risk. Do not use for small execute-task changes, pure refactors, or already-approved design decisions.

Use when the user has a rough product, workflow, or system idea and wants to decide whether it is worth doing before creating a spec. Focus on value, fit, build-vs-reuse/open-source/SaaS alternatives, smallest useful scope, and a clear verdict: do-now, defer, reject, reuse-or-integrate, or research-more. Do NOT use when a spec already exists, when the user only wants open-ended brainstorming, or when the task is already a small implementation request.

Run a progress-gated, multi-epoch GNHF implementation from an approved feature spec, preserve each successful iteration as a Git commit in an isolated worktree, enforce feature-level budgets, and hand explicit workspace and artifact contracts back to the repository orchestrator. Use for the execute-gnhf step of an implementation workflow or when the user explicitly wants GNHF to implement an already reviewed spec.

Use when the user asks to implement a feature or user-visible bug fix from a spec file. Executes directly from the spec and writes an implementation summary.

Use when the user asks for a small local update, narrow bug fix, or refactor that does not need a durable spec.

Use when the human wants to execute a documented workflow config end-to-end until the next gate, blocker, or manual stop. Reads `docs/ai/workflows/*.json`, runs inline/skill/subagent steps in order, persists run state, and enforces contract-based dependencies. Do not use for free-form planning or when no workflow config exists.

Use when writing or updating Swagger/OpenAPI docs, documenting new endpoints, reviewing existing API docs for completeness, or generating OpenAPI spec from code. Skip when the API is internal-only with no external consumers and no doc requirement. Skip when making API design decisions (endpoint naming, HTTP conventions, versioning strategy) — use api-design instead.

Use when implementing login/auth flow, designing token strategy, adding permission/role checks, building auth middleware, reviewing auth security, or choosing between auth approaches. Skip when auth system is already fully defined and task is routine implementation with no design choices. Skip when running a post-implementation security audit — use be-security-check instead.

Select, create, validate, or serve facts and predeclared consequences for a software-engineering learning case. Use internally from learning-workflow or directly when the human wants to prepare, inspect, validate, or create a case. Do not coach, assess the learner, or run experiments.

Use when the user asks to remove, delete, or disable a feature. Inventories all surfaces, analyzes dependencies, chooses deletion strategy, and verifies completeness. Do not use for bug fixes, refactoring, or partial UI changes that are not feature removals.

Use when the user asks to verify implementation-level evidence (code tests, build checks, API checks) against an approved spec and its structured testcase definitions. Appends detailed evidence to the verification record without touching the checklist.

Use when the user asks to run real browser-driven end-to-end verification against an approved spec and its structured testcase definitions. Loads the project E2E tool and environment definitions, exercises observable user flows through the configured browser tool, appends detailed evidence to the verification record without touching the checklist.

Assess a learning session from recorded attempts, revisions, assistance, case facts, rubric, and system evidence; classify gaps and recommend one next action. Use internally from learning-workflow or directly to reassess or dispute a completed scope. Do not coach, reveal an open solution, or rewrite the learner's answer.

Strengthen a raw user prompt into an execution-ready instruction set for an AI agent. Use when the user wants to improve an existing prompt, build a reusable prompting framework, wrap the current request with better structure, add clearer tool rules, or create a hook that upgrades prompts before execution. Do not use for already-specific requests, straightforward questions, or simple bug fixes.

Use when the human wants to validate verification evidence and update the checklist with final status. Reads the testcase definitions and verification record, validates completeness, and updates the checklist. Do not use to write production code, run tests, or repair failures.

Create a Vietnamese spec-derived testcase checklist and structured testcase definitions after implementation so verification can update evidence status and the human can validate only the remaining cases. Runs automatically under supported orchestrator workflows and may be invoked directly to regenerate the checklist from an approved spec.

Post-implementation backend security review scoped to a feature or flow: injection, broken auth, mass assignment, sensitive data exposure, missing rate limiting, improper authorization, business flow abuse, misconfiguration (OWASP API Security Top 10 2023). Use when: a backend feature has been implemented and needs a security pass before PR review or merge. Trigger phrases: "check security", "security review backend", "security audit", "security check after implementation". Skip when task is purely frontend styling, config-only change, or documentation update with no logic. SCOPE: always review only the files changed in the current feature/PR.

Execute an explicitly authorized research, spike, test, simulation, benchmark, model, or failure-injection request for an active learning case and return bounded system evidence with limitations. Use internally from learning-workflow or directly for a recorded evidence request. Do not choose protected evidence for the human or assess competency.

Start, resume, or stop a realistic software-engineering learning session through a simple Explore, Decide, Reflect conversation while preserving the human's ownership of assessed judgment. Coordinates case, evidence, and review helpers internally. Do not use for ordinary software delivery or direct tutoring without an active learning case.

Use when the user wants a read-only thinking partner to break down a vague idea, hard bug, unclear feature logic, or difficult technical decision before implementation. Focus on dialogue, codebase inspection, grounded hypotheses, web research when needed, and concrete next steps without editing files.

Use when the task involves linting, type checking, build verification, or debugging failing validation. Prefer project-native commands and focused checks before broad fixes.

Evaluate, compare, improve, promote, reject, or review an AI workflow. For workflow improvement and usage diagnosis, analyze real session history trace-first to find agent friction, rework, retries, human intervention, and first divergence before mapping findings back to workflow rules. For new-workflow adoption without traces, review artifacts and controlled exercises. Writes a Vietnamese HTML report to docs/ai/evaluation/reports/.

Post-implementation backend performance review scoped to a feature or flow: N+1 queries, missing indexes, unbounded queries, blocking I/O, memory leaks, caching gaps. Use when: a backend feature has been implemented and needs a performance pass before PR review or merge. Trigger phrases: "check performance", "performance review", "optimize backend", "review queries", "N+1 check". Skip when task is purely frontend, config change, or documentation update. SCOPE: always review only the files changed in the current feature/PR.

Use when working on React or Next.js performance, rendering behavior, data fetching, Suspense, bundle size, or component architecture. Do not use for styling-only tasks.

User feedback patterns: loading states, success/error messages, form validation, empty states. Use when: form submissions, async loading indicators, error handling flows, empty state designs. Keywords: loading, success, error, form, validation, async, feedback, toast, empty state, API call Do NOT use for: visual styling, responsive layout, Figma extraction, accessibility-only.

Record any observable problem, blocker, ambiguity, retry, rework, workaround, human correction, tool failure, runtime issue, task-context issue, or workflow friction encountered while an AI agent is running. Use only when the human explicitly asks to note, capture, or log the current execution difficulty for later analysis. Do not assume the workflow caused the problem, and do not fix or replace the active task.

Mobile-first responsive design: breakpoints, fluid layouts, touch optimization. Use when: user mentions responsive, mobile, tablet, multiple devices, or touch. Keywords: responsive, mobile, tablet, desktop, breakpoints, multi-device, viewport, screen size, touch Do NOT use for: desktop-only, general styling (→ frontend-design-fundamentals).

Base design skill for ALL frontend/UI work: spacing, typography, colors, visual hierarchy. Use when: any frontend/UI task — styling, CSS, components, layouts, animations. Keywords: frontend, UI, CSS, styling, layout, spacing, typography, card, button, form, dashboard, animation, hover, shadow Do NOT use for: backend, DevOps, React performance (→ react-best-practices).

Theme/color selection when user has no aesthetic direction and wants agent to decide. Use when: user is uncertain — "suggest colors", "what theme", "help me choose", "you pick". Keywords: suggest theme, suggest colors, what theme, what colors, help choose, help pick, no direction, you choose, recommend colors Do NOT use for: user has colors/style in mind, applying existing theme.

Use when the user wants to extract a Figma frame into `docs/ai/features/designs/DD-MM-YYYY-figma-{name}.md` with exact specs, partial-progress support, and large-frame handling.