setting: CI 및 에이전트 워크플로우 기준 정리

.agents/skills/api-integration-workflow/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: api-integration-workflow
+description: Use this when adding API helpers, request/response types, TanStack Query hooks, query keys, or cache behavior.
+---
+
+# API Integration Workflow
+
+## Purpose
+
+Implement predictable API boundaries and React Query usage for Roominus Admin.
+
+## Read First
+
+- `AGENTS.md`
+- `.agents/skills/project-conventions-workflow/SKILL.md` for file naming and commit conventions when relevant
+- Existing API/client/query patterns in `src/features` and `src/shared`
+- Endpoint docs or backend contract supplied by the user
+
+## Required Inputs
+
+- HTTP method and path
+- Request params, search params, or body
+- Response shape
+- Expected error shape, if known
+- Usage site or page
+
+If the API contract is unclear and cannot be inferred from local code, ask before inventing fields.
+
+## Rules
+
+- Keep request/response types close to the API boundary.
+- Include every response-changing input in the query key.
+- Prefer domain-local API helpers first. Promote to `src/shared` only when multiple real users exist.
+- Do not add optimistic updates, retries, or broad invalidation unless the UX needs them.
+- Surface errors explicitly enough for the page to render useful states.
+- Keep mapping/normalization near the boundary when it protects the UI from backend shape changes.
+
+## Implementation Flow
+
+1. Find existing `axios` and `@tanstack/react-query` usage.
+2. Add or reuse a typed API helper.
+3. Add query keys before hooks when caching is involved.
+4. Add query or mutation hooks with narrow inputs and readable return values.
+5. Wire the hook into the page or component without mixing transport details into UI.
+6. Verify lint/build according to change risk.
+
+## Done Criteria
+
+- Types describe the API boundary.
+- Query keys include response-changing inputs.
+- Cache invalidation or update behavior is intentional.
+- Errors are not silently swallowed.
+- Verification is run or the skipped check is explained.

.agents/skills/api-integration-workflow/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: 'API Integration Workflow'
+  short_description: 'Add API helpers and React Query hooks.'
+  default_prompt: '$api-integration-workflow로 API 연동과 query key/cache 동작까지 구현해줘.'
+policy:
+  allow_implicit_invocation: true

.agents/skills/form-flow-workflow/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: form-flow-workflow
+description: Use this when implementing form validation, submit flows, mutations, and loading/error/success states.
+---
+
+# Form Flow Workflow
+
+## Purpose
+
+Implement predictable form behavior for Roominus Admin screens, including validation, submit state, server errors, and success handling.
+
+Use this with `api-integration-workflow` when a form submits to an API or uses a React Query mutation.
+
+## Read First
+
+- `AGENTS.md`
+- `.agents/skills/page-feature-workflow/SKILL.md` for route ownership
+- `.agents/skills/api-integration-workflow/SKILL.md` when submit calls an API
+- Existing forms or input patterns in `src/app`, `src/features`, and `src/shared`
+
+## Required Inputs
+
+- Fields and input types
+- Validation rules and user-facing error messages
+- Submit behavior
+- Loading, disabled, failure, and success behavior
+- API request and error shape when server-backed
+
+If validation or submit behavior is unclear and cannot be inferred from nearby code, ask before inventing business rules.
+
+## Rules
+
+- Keep field state, validation, submit orchestration, and transport concerns separated enough to read.
+- Do not hide server errors silently.
+- Disable submit only for intentional conditions such as invalid input, unchanged state, or in-flight submission.
+- Keep validation messages close to the relevant field when possible.
+- Ensure labels, focus-visible states, keyboard submission, and error association are usable.
+- Keep API payload mapping near the API boundary when it protects UI code.
+
+## Implementation Flow
+
+1. Decide whether the form belongs in the page, a route-local component, a feature component, or shared UI.
+2. Map each field to its source of truth, validation rule, and displayed error.
+3. Separate client validation from server error handling.
+4. Add mutation or submit logic with explicit loading and failure states.
+5. Handle success intentionally: refetch, invalidate, navigate, close dialog, or show feedback.
+6. Check keyboard flow, disabled behavior, and layout stability.
+7. Run targeted verification.
+
+## Done Criteria
+
+- Validation matches the requested behavior.
+- Submit state and disabled state are intentional.
+- Server errors are visible or otherwise handled deliberately.
+- Loading, failure, and success states are consistent.
+- Accessibility basics are covered for labels, focus, and error text.
+- Verification is run or the skipped check is explained.

.agents/skills/form-flow-workflow/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: 'Form Flow Workflow'
+  short_description: 'Implement validation and submit state for forms.'
+  default_prompt: '$form-flow-workflow로 Roominus Admin 폼 흐름을 구현해줘.'
+policy:
+  allow_implicit_invocation: true

.agents/skills/frontend-fundamentals-review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: frontend-fundamentals-review
+description: Use this when reviewing frontend diffs for readability, predictability, cohesion, coupling, and logic composition.
+---
+
+# Frontend Fundamentals Review
+
+## Purpose
+
+Review frontend changes for maintainability risks beyond formatter, lint, and build results.
+
+Use this for non-trivial React, page, component, hook, or API wiring changes. Skip it for docs-only or formatting-only edits.
+
+## Read First
+
+- `AGENTS.md`
+- The current diff or requested files
+- Nearby components, hooks, API helpers, and usage sites
+- Relevant workflow skills for the changed area, such as `page-feature-workflow`, `shared-component-workflow`, `form-flow-workflow`, or `api-integration-workflow`
+
+## Review Criteria
+
+- Readability: names, control flow, component shape, and JSX structure are easy to scan.
+- Predictability: props, state, effects, keys, memoization, and return values behave as callers expect.
+- Cohesion: responsibilities stay close to the code that owns them.
+- Coupling: route, copy, API, analytics, and styling details do not leak into generic code.
+- Logic composition: extracted helpers or hooks have a real responsibility and stable usage sites.
+
+## Common Checks
+
+- Avoid render-time side effects.
+- Avoid copying props into state without a clear synchronization rule.
+- Avoid conditional hook calls, unstable list keys, and unnecessary `useMemo` or `useCallback`.
+- Keep presentational components free of transport details.
+- Keep route-only behavior out of shared components.
+- Do not extract a hook only because a component is long.
+- Prefer pure helpers for mapping, formatting, grouping, and validation that do not need React state.
+
+## Output Shape
+
+When reviewing, lead with findings:
+
+```markdown
+Findings:
+
+- [Severity] `path/to/file.tsx:line` - Issue.
+  Fix: Suggested change.
+
+Open questions:
+
+- Question, if any.
+
+Residual risk:
+
+- Anything not checked.
+```
+
+If no issues are found, say that clearly and mention any remaining verification gap.
+
+## Done Criteria
+
+- Findings are tied to files and lines when possible.
+- Suggestions are actionable and scoped.
+- Taste-only preferences are separated from correctness or maintainability risks.
+- Lint/build results are not treated as a substitute for review judgment.

.agents/skills/frontend-fundamentals-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: 'Frontend Fundamentals Review'
+  short_description: 'Review frontend diffs for maintainability risks.'
+  default_prompt: '$frontend-fundamentals-review로 현재 프론트엔드 변경사항을 리뷰해줘.'
+policy:
+  allow_implicit_invocation: true

.agents/skills/frontend-quality-verification/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: frontend-quality-verification
+description: Use this after Roominus Admin frontend changes to choose and run the smallest useful verification commands.
+---
+
+# Frontend Quality Verification
+
+## Purpose
+
+Pick checks that match the actual change. Keep verification light, but do enough to prove the work.
+
+## Read First
+
+- `package.json`
+- Changed files from `git status --short` or `git diff --name-only`
+
+## Verification Ladder
+
+| Change Type                                                            | Checks              |
+| ---------------------------------------------------------------------- | ------------------- |
+| Docs or agent files only                                               | `git diff --check`  |
+| Formatting-sensitive docs or code                                      | `pnpm format:check` |
+| TypeScript, React, or shared UI changes                                | `pnpm lint`         |
+| Next route, config, build, or Server/Client Component boundary changes | `pnpm build`        |
+
+Use `npm run ...` only if pnpm is not available in the environment.
+
+## Rules
+
+- Do not claim a check passed unless it was run successfully.
+- If a check fails, separate failures caused by the current change from pre-existing failures when possible.
+- If a check cannot run because dependencies or environment are missing, report that plainly.
+- For UI changes, mention any manual browser check that still matters.
+
+## Output Shape
+
+```markdown
+Verification:
+
+- `command`: pass/fail/not run
+- Notes:
+```

.agents/skills/frontend-quality-verification/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: 'Frontend Quality Verification'
+  short_description: 'Choose and run the right frontend checks.'
+  default_prompt: '$frontend-quality-verification으로 이번 변경에 맞는 검증을 해줘.'
+policy:
+  allow_implicit_invocation: true

.agents/skills/frontend-task-orchestrator/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: frontend-task-orchestrator
+description: Use this to classify Roominus Admin frontend work, pick the smallest relevant skill, and decide what context and verification are needed.
+---
+
+# Frontend Task Orchestrator
+
+## Purpose
+
+Use this before non-trivial frontend work. Decide the task type, gather only the context needed, and route the work to the right lightweight workflow.
+
+## Read First
+
+- `AGENTS.md`
+- Relevant files found with `rg` or `rg --files`
+- For Next-specific changes, the closest matching file under `node_modules/next/dist/docs/01-app/`
+
+## Task Routing
+
+| Work Type                                                             | Use                               |
+| --------------------------------------------------------------------- | --------------------------------- |
+| Naming, assets, styling units, branch names, commit messages          | `project-conventions-workflow`    |
+| New or changed App Router page, layout, route-local UI                | `page-feature-workflow`           |
+| Next Server/Client Component boundary decision                        | `server-client-boundary-workflow` |
+| Reusable UI component under `src/shared/components`                   | `shared-component-workflow`       |
+| Form validation, submit, disabled/loading/error/success state         | `form-flow-workflow`              |
+| API helper, request/response type, query key, query/mutation hook     | `api-integration-workflow`        |
+| Frontend code quality review for a non-trivial diff                   | `frontend-fundamentals-review`    |
+| GitHub issue drafting, issue refinement, issue breakdown              | `issue-workflow`                  |
+| Pull request summary, checklist, issue link, review-ready description | `pr-prep-workflow`                |
+| Verification after docs or code changes                               | `frontend-quality-verification`   |
+
+Do not invoke heavier workflows for Jira, Turbo, monorepos, design-system packages, PR monitoring, or browser PR review unless they are explicitly introduced to this repo.
+
+## Checklist
+
+1. Identify the user-visible goal and success criteria.
+2. Confirm the affected route, feature, shared component, or API surface.
+3. Read nearby existing code before choosing structure.
+4. Apply `project-conventions-workflow` when naming files/components/assets, suggesting branches, or drafting commits.
+5. Keep route-local code local until reuse is real.
+6. Choose verification before finishing.
+
+## Output Shape
+
+When a plan is useful, keep it short:
+
+```markdown
+## Frontend Work Plan
+
+- Task type:
+- Target files:
+- Skill:
+- Missing context:
+- Verification:
+```

.agents/skills/frontend-task-orchestrator/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: 'Frontend Task Orchestrator'
+  short_description: 'Classify frontend work and choose the light workflow.'
+  default_prompt: '$frontend-task-orchestrator로 이 프론트엔드 작업의 범위와 진행 순서를 정리해줘.'
+policy:
+  allow_implicit_invocation: true

.agents/skills/issue-workflow/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: issue-workflow
+description: Use this when drafting, refining, splitting, or reviewing GitHub issues for Roominus Admin, including bug reports, feature requests, custom tasks, labels, title prefixes, acceptance criteria, TODO lists, reproduction steps, and references.
+---
+
+# Issue Workflow
+
+## Purpose
+
+Create concise GitHub issues that match this repo's templates and are ready to implement.
+
+## Read First
+
+- `AGENTS.md`
+- Matching template under `.github/ISSUE_TEMPLATE/`
+- `.github/labeler.yml` when choosing a title prefix
+- Nearby source files only when issue scope depends on current implementation
+
+## Template Selection
+
+| Issue Type           | Template                                    | Title Prefix |
+| -------------------- | ------------------------------------------- | ------------ |
+| New feature          | `.github/ISSUE_TEMPLATE/feature_request.md` | `[FEAT]`     |
+| Bug fix              | `.github/ISSUE_TEMPLATE/bug_report.md`      | `[FIX]`      |
+| API work             | `.github/ISSUE_TEMPLATE/custom.md`          | `[API]`      |
+| Refactor             | `.github/ISSUE_TEMPLATE/custom.md`          | `[REFACTOR]` |
+| Docs                 | `.github/ISSUE_TEMPLATE/custom.md`          | `[DOCS]`     |
+| Style/UI-only polish | `.github/ISSUE_TEMPLATE/custom.md`          | `[STYLE]`    |
+| Test work            | `.github/ISSUE_TEMPLATE/custom.md`          | `[TEST]`     |
+| Config/setup         | `.github/ISSUE_TEMPLATE/custom.md`          | `[SETTING]`  |
+
+Use another labeler prefix from `.github/labeler.yml` only when it clearly fits better.
+
+## Writing Rules
+
+- State the problem or goal in observable product terms.
+- Keep TODO items implementation-sized and checkable.
+- Include acceptance criteria when the requested behavior could be ambiguous.
+- For bugs, include current behavior, expected behavior, and reproduction steps.
+- For UI work, mention target route, state, and viewport if known.
+- For API work, mention endpoint, method, request inputs, response shape, and error behavior if known.
+- Do not invent screenshots, links, owners, labels, or timelines.
+- Ask only when missing information would make the issue misleading.
+
+## Output Shape
+
+Use this structure when the user asks for issue text:
+
+```markdown
+Title: [PREFIX] Short concrete title
+
+## Summary
+
+## Details
+
+## TODO
+
+- [ ] ...
+
+## Acceptance Criteria
+
+- [ ] ...
+
+## References
+```
+
+For bug reports, replace `Details` with:
+
+```markdown
+## Current Behavior
+
+## Steps To Reproduce
+
+## Expected Behavior
+```
+
+## Done Criteria
+
+- Title prefix matches intended label.
+- The issue can be implemented without rereading the conversation.
+- TODO and acceptance criteria are testable.
+- Unknowns are clearly marked instead of guessed.