A web app/site that runs on Kurocoentirely from scratchAn orchestration skill for building. Individual implementation details are delegated to specialized skills (described later), and this skill focuses onthe approach (phase design) and bridging.
Execution environment: Codex Sites（chatgpt.site) cannot be operated from ChatGPT's normal chat, so
for building Kuroco, running in Work mode (ChatGPT's workspace) or Codex is recommended.
When proceeding in normal chat, the publication destination is KurocoFront (/kuroco-frontend-integration "Determining the publication destination").
Basic policy: Frontend-first (mock-first)
Kuroco's standard build order is "content definition → API → frontend", but for users, seeing a working screen first is the easiest to understand. Therefore, this skill reverses the order: first build and show a frontend that runs on mock data, and once the screens are finalized, build the backend to match the screens.
フェーズ0 フェーズ1 フェーズ2 フェーズ3 フェーズ4 フェーズ5
要件ヒアリング → モックで画面構築 → コンテンツ定義 → API作成 → 実データ接続 → 最終セキュリティ点検
（機能→Kuroco （ユーザーが見て ・データ投入 ・セキュリティ ・書き込み接続 ・security-audit
対応付け） フィードバック） （Admin MCP） 設定 ・デプロイ ・指摘の反映
↑ ここで見た目を確定してから先へ進む ↑ ここを飛ばして完了報告しない
The key to making this order work iscreating the mock data from the start in the shape (contract) of the Kuroco API response. After the screens are finalized, you only need to replace the mock implementation with real API calls. For contract details and implementation patterns: references/mock-contract.md
This is the default pattern (Pattern A) and is not the only approach. If the data model is already finalized, or if the frontend is being built by another team, switch to a different pattern—for the criteria, see0-2. Determining the approach pattern.
Progress checklist
At the start of the build, copy this checklist and check items off as you progress:
アプリ構築の進行:
- [ ] 0-0. Admin MCP の接続確認（未接続ならヒアリングに入る前に接続を終わらせる。ツール追加後にセッションの作り直しが要るクライアントでは、ヒアリング後に接続すると0-1〜0-5の合意が会話ごと失われる。**Kurocoサイトがまだ無ければ先に [references/create-site.md](references/create-site.md) で新規作成してから接続する**）
- [ ] 0-1. 要件ヒアリング（目的・業務範囲、ロール、画面、データと明細、データごとの状態、添付、規模、デバイス方針、デザイン方針、デモデータ）
- [ ] 0-2. 進め方パターンの決定（A モックファースト / B バックエンド先行 / C 担当外。理由を明記）
- [ ] 0-3. 機能→Kurocoマッピング表 ＋ ロール×画面の権限マトリクス ＋ データごとのステータス遷移表の作成・ユーザー合意（状態は承認ワークフローと独自ステータス項目に振り分ける）
- [ ] 0-4. 外部システム連携パターンの決定（直接呼び出し / プロキシ / 取り込み。連携先ごとに選ぶ。連携なしも明記）
- [ ] 0-5. 認証方式**と到達経路の制限**の決定（①誰に見せるか＝認証方式 ②どこから見せるか＝IP制限/Basic認証。**2つとも書く**。以降の設計全体に波及する）
- [ ] 0-6. 接続先サイトと構築制約の確定（0-0 で接続済みであることを前提に、`whoami` で対象サイトの同定・`mcp:tools.all` 以上か・拡張項目/繰り返し/カテゴリの現行上限を確定する。不足のままフェーズ2に入ると3-1で失敗する）
- [ ] 0-7. 引き継がれた既存設定の棚卸し（**サイトは必ずコピーで作られる**ため、API定義・エンドポイント・コンテンツ定義が最初から入っている。`site.copy_from_site_key` でコピー元を確定し、流用しないものは承認を得て**先に無効化／削除**。`group_id` 100以下は対象外）
- [ ] 1-1. フレームワーク選定とプロジェクト雛形作成（パターンB/Cでは該当する場合のみ）
- [ ] 1-2. Kurocoレスポンス形のモックデータ + APIクライアント層の実装（**パターンAのみ**。パターンBは実APIを直接呼ぶため不要）
- [ ] 1-3. 画面実装 → ユーザーレビュー → フィードバック反映（確定まで繰り返し）
- [ ] 2-1. Admin MCP 接続確認（フェーズ0で未接続のまま進めた場合はここで再確認。スコープ不足なら着手しない）
- [ ] 2-2. 確定画面から逆算したコンテンツ定義の作成
- [ ] 2-3. カテゴリ・タグ・マスタ（テーブルデータ）の設定
- [ ] 2-4. サンプルコンテンツ投入（モックと同内容だと差し替え検証が楽）
- [ ] 2-5. （必要なら）メンバー・認証、フォーム、お気に入り・コメント、承認ワークフローの設定
- [ ] 3-1. エンドポイント作成（Topics::list / details 等。0-4でプロキシ/取り込みを選んだものはカスタムSmarty処理）
- [ ] 3-2. セキュリティ設定（**0-5①の認証方式** ＋ **0-5②のAPI単位IPアドレス制限**）とCORS・キャッシュ設定、Admin MCP でのエンドポイント定義の確認
- [ ] 3-3. モック契約との突き合わせ（実キー名・カテゴリID・API ID/パスの確定、モック側の訂正。**パターンAのみ**）
- [ ] 3-4. 対応表との網羅照合（0-3成果物1の**各行**が `api-export_openapi` の出力に存在するかを**行単位で照合**。欠けている行は「作らない」と0-3に記録がない限り**未実装**として3-1に戻る。**全パターン共通**。3-3は「形」、3-4は「網羅」の照合で別工程）
- [ ] 4-1. モック→実APIへの切り替え・**読み取り**の表示確認（パターンBは1-1〜1-3が既に実API接続のため該当なし）
- [ ] 4-2. **書き込み操作の接続**（対応表で「フロント実装」とした insert / update / 削除 / 承認・差し戻しと、CSV等の出力、認証フローの**すべて**。**各画面の書き込み操作を1つずつ実行し、Kuroco側にレコードが入ることを Admin MCP の読み取りで確認する**。出力はレコードを残さないので、取得したファイルの件数・項目が Kuroco 側の実データと一致することで確認する。対応表に書き込み・出力の行が1つも無い場合だけ「該当なし＋対応表の該当箇所」で満たす）
- [ ] 4-3. 公開先の確認（既定はKurocoFront。指定があればその公開先）→ デプロイ（KurocoFront: Admin MCP直接デプロイ or GitHub連携）または起動手順の提示。**0-5②でフロント側の到達経路制限を決めた場合は `kuroco_front.json` の `ip_restrictions` / `basic` をここで設定する。0-5②が「制限なし」でも、ユーザーが公開を明示するまでは非公開デフォルト（robots.txt の `Disallow: /` ＋ Basic認証/IP制限の選択）を適用する**（`/kuroco-frontend-integration` の「非公開デフォルト」）
- [ ] 4-4. 後戻り更新: フェーズ2・3で確定した実際の値（拡張項目の実キー名と割当・カテゴリID・エンドポイントのパス）を、フェーズ1で作ったマッパー／定数ファイルに書き戻す
- [ ] 4-5. 画面ごとのAPI接続状況表（画面 × 操作（読み取り／書き込み／出力） × 接続済みか）を成果物として提示（**未接続の行が残ったまま完了報告しない**。残す行は「作らない」の合意と理由を併記する）
- [ ] 5-1. `/kuroco-security-audit` で最終点検（**本番デプロイ前**）
- [ ] 5-2. 指摘の反映（該当フェーズに戻って修正。**使わなくなったAPI／エンドポイントは無効化**。直さないものは理由と受容者を記録）
- [ ] 5-3. 通しで再監査（**全項目そろって問題ない状態を確認してから完了報告**）
Use the following 5 symbols.Do not delete entire rows(because it becomes impossible to read who handled what and how).
| Symbol | Meaning | Entry condition |
|---|---|---|
[x] |
Complete | Deliverable has been produced |
[~] |
Satisfied by alternative means | Satisfied the alternative acceptance condition of "Default behavior when preconditions cannot be met" (also note what was used as the alternative) |
[!] |
Intentionally paused | Preconditions could not be met andit was stopped (agreement could not be reached, connection failed, etc.).Add one line stating the resumption condition. For steps where the requester has indicated a delivery milestone and work simply has not started yet, [!] not [ ] |
[-] |
Out of scope | Do not perform it yourself.（担当外: 〇〇チーム） and the person in charge listed together |
[ ] |
Not started | Other than the above |
The values written back in 4-4 (the actual key names and assignments of extension items, category IDs, endpoint paths and API IDs, and filter syntax) are:Decide on the minimum number of aggregation destination files, and do not write anywhere other than those. Decide the aggregation destinations at the phase 1 stage, and clearly state the file names in the deliverables.
Default behavior when preconditions cannot be met
This skill includes processes that presuppose user responses, external connections, and delegation to other skills.Even in an environment where preconditions cannot be met, do not stop; take the default behavior in the table below for each type of dependency. Apply the same principle when encountering a dependency not in the table — "Do not skip over it on your own. Create deliverables up to what can be finalized, and explicitly indicate the parts that cannot be finalized, then stop."
| Type of dependency | Default behavior when it cannot be met | Checklist symbol |
|---|---|---|
Questions to the user（AskUserQuestion cannot be used) |
Proceed by making assumptions. Create a "Confirmation Items" section in the deliverables, and for each assumption andthe scope of impact if it turns out to be wrong, write one line each.For the scope of impact, distinguish whether it is a "design redo" or an "implementation replacement"(Only the former goes on the agreement gate. If 10 assumptions line up, it becomes impossible to tell which should be confirmed first.) | [~](Satisfied by assumption. Also state what was assumed) |
| User agreement(No response obtained) | Proceed as provisional agreement, andstop immediately before operations that involve writing to Kuroco(content definition creation, data input, endpoint creation, deployment). Read operations and work completed within your own working directory may continue | For processes that produced deliverables, [~](provisional agreement).For stopped writing processes, [!] + resumption condition "agreement to this design" |
| A specific Admin MCP function does not work(Can connect, but a certain tool does not save as expected or returns an error) | Treat this separately from being unable to connect.Try once with the same kind of minimal data to isolate the issue, and once it is confirmed not to work, switch to an alternative means that does not drop requirements (a different field type, procedural guidance in the admin screen) and move forward. Clearly state in the deliverables the parts that were replaced and what you originally wanted to do. Do not keep trying the same format over and over | [~](Also state the alternative means) |
| Human review(Cannot have the screen checked) | Treat all of the following three points as alternative acceptance conditions: ① The build/static generation succeeds ② The main routes are generated and respond (list, detail, error pages) ③ The result of inspecting that the items listed in the requirements are included in the generated output. Attach a bulleted list of points you want checked | If all three points are satisfied, [~], and if they are not satisfied, [!] |
| Admin MCP connection(not connected / authentication not possible) | Write out the tool calls scheduled to be executed and their input JSON inthe procedure document with concrete values and stop | [!] + resumption condition "Admin MCP connection / reauthorization" |
Delegation to other skills（/kuroco-* cannot be read) |
You may fill it in with your own knowledge, but **clearly mark** the filled-in parts as "unverified" and put them in the items to be confirmed. Do not write in assertive form | [~](write alongside "unverified") |
If multiple dependencies cannot be satisfied at the same time, apply all applicable default behaviors and adopt the earliest stopping point.
"Permission to write" and "agreement on the design" are separate gates. Confusing them leads to creating an unapproved design with approved permissions.
| gate | Who grants it | Handling when it is not satisfied |
|---|---|---|
| Write permission(whether it is okay to write in this environment) | The requester/operator. The Admin MCP scope and the requester's explicit permission | Do not write. Put it in the procedure document and stop (the "Admin MCP connection" row in the table above) |
| Agreement on the design(whether what is being built is correct) | The owner of the requirements | Proceed as a provisional agreement, andstop immediately before writing(the "user agreement" row in the table above) |
The scope of the gate's effect is defined only here. Even if other sections (such as 0-3) say "proceed only after obtaining agreement," the meaning follows this definition.
- Agreement on the design is a gate for "writing to Kuroco," not a gate for phase transitions. Even in an environment where agreement cannot be obtained, Phase 1 (mock implementation = completed within your own working directory) may proceed.
- HoweverIf the requester has explicitly specified a delivery boundary(such as "show me the design first" or "just the design first"),that boundary becomes an independent stopping point. Present the Phase 0 deliverables and stop, leaving Phase 1 and later in the progress checklist as
[ ](not started). If no boundary is explicitly specified, you may proceed to Phase 1.
Even if write permission has been granted in advance, thatdoes not substitute for agreement on the design. If you proceed to writing based on the permission, state that "the design was executed without agreement" andScope that will require changes later(content definitions and already-ingested data that will need to be recreated) must be explicitly stated in the deliverables.
Source of information and timing of acquisition
At the point of creating mocks or content definitions, the API does not exist yet.Do not fill in the information in the table below by guessing. Always verify information whose source is "always available", and place information that cannot yet be obtained at that time as placeholders in the aggregation file (see 4-4).
| Information | Source | Timing when it can be obtained |
|---|---|---|
Response shape ({ list, pageInfo } / { details }）、pageInfo key names,filter / order syntax, Topics standard fields, relationship between cache unit and authentication |
/kuroco-docs（reference-api-2.md / reference-api-3.md / reference-content-1.md） |
Always available. Specifications determined by the model/operation, and do not vary by site |
| Effective scope and effective permissions of the connection | Admin MCP の whoami |
After connection.Verify in Phase 0（0-6） |
Admin MCP tool names and inputSchema |
Admin MCP の tools/list |
After connection |
Key naming for extended fields (ext_1 format or ext_col_01 format.Varies per site） |
Admin MCP の whoami（site.topics_ext_key_format） |
After connection |
Current upper limits of the content structure (number of extended fields, number of rows in repeating groups, number of categories, number of member extended fields) andnumber／searchable/ availability of structured JSON |
Admin MCP の whoami（site.limits.* は {current, max}、site.topics_ext_features） |
After connection.Verify in Phase 0(0-6③). Count whether the design exceeds these upper limits before 0-3 and 2-2 |
| Actual key names and assignments of content definition fields and extended fields | Admin MCP の topics-describe(authoritative per group) |
Phase 2 onward |
| Actual IDs of categories and tags | Admin MCP (reading the category list) | Phase 2 onward |
| API ID, endpoint path, actual request/response definitions | Admin MCP の api-export_openapi（api_id required,format は json/yaml). OpenAPI 3.1.0 is returned |
Phase 3 onward |
for placeholdersUndetermined types and verification methodsmust be included. Labels alone do not let the recipient estimate the verification cost.
| Type | Meaning | Verification method |
|---|---|---|
| Existence unconfirmed | It is unknown whether the feature or endpoint itself exists | /kuroco-docs / tools/list |
| Name unconfirmed | It should exist, but the exact name is unknown | tools/list actual name |
| Shape unconfirmed | The structure of the response/request is unknown | /kuroco-docs corresponding reference |
| Actual value undetermined | The structure is known, but the value for this site is undetermined | Admin MCP reads (finalized in Phases 2 and 3) |
| Not provided by the requester | Cannot be obtained from the Kuroco side, andValues only the requester has(Internal network egress IP, proprietary domain, department list, logo, internal terminology) | Confirm with the requester.Settings that will not fall to the safe side if these values are not filled in (IP restriction allowlist, CORS allowed origins) must not proceed to the writing process until the values are finalized——If you configure them empty or with placeholder values, you end up in a state that looks closed but is actually open |
Stop pointsBy type of action, not phase numberare defined this way so that even if Pattern B/C is selected in 0-2 and the order is swapped, the stop positions do not shift.
How much to read for this project (read differentiation)
This skill does not assume reading the full text for every project. If the conditions below apply, you may proceed without reading the relevant sections——the goal is not to reduce the amount read, butto avoid skipping in projects where they do not apply, the conditions are stated explicitly.
| Conditions | Sections that do not need to be read |
|---|---|
| The request is "show me the design first," etc., andPhase 0 is the delivery boundary | The main text of Phases 1–5 (the checklist is included in the deliverable, so looking only at item names is sufficient).However, read the decision criteria table for "1-1 Framework Selection"——because 0-1 #14 refers to this to finalize it, treat it as part of Phase 0 |
| 0-3でIt was determined that an approval workflow will not be used(No rework, explicitly stated that approval is not required) | In 0-3 "Decide how to hold state (status)," the part after the routing table (handling of rejection, retrieval of in-progress data, composition rules).Always read up to the routing table and decision axes |
| 0-2でPattern A was selected | The "Supplement for Patterns B and C" section.However, "whether to create a new API definition or piggyback on an existing one" in the same section is also used in Pattern A(because endpoints with different authentication methods cannot be mixed into the same API definition, it is needed for the split decision in 0-5①) |
| There is no data containing multiple rows within one record (line items) | "How to hold line items (one-to-many)" (feature-mapping).Note: "no line items" and "no one-to-many relationship" are different——one-to-many where parent and child are separate records (events and applications, slots and reservations) is not a line item but a relation decision, so this table does not need to be read, butwrite it in deliverable ④ as a parent-child relationship |
| Aggregation and graph requirements arenot | the "Aggregation, Reports, Graphs" row in feature-mapping |
Phase 0 (0-0 to 0-7) and "Default behavior when prerequisites cannot be met" should not be skipped in any project.
references/spec-notes.md はFor conservative users(A list of descriptions written because the current specification is hard to understand, and their deletion conditions).No need to read this during build work.
Timing for reading the referenced files: references/feature-mapping.md はUsed in Phase 0(Concrete forms of hearing items, presets, deliverable templates).references/mock-contract.md はUsed in Phase 1(Mock response contract) — For projects that stop by Phase 0, it is enough to look only at the key naming of extension items and the section on standard items that do not appear in responses.references/create-site.md はUsed only in a cold start where there is no Kuroco site yet(Starting from 0-0) — No need to read this for projects already connected to an existing site.
Phase 0: Requirements hearing and design
0-0. Connecting Admin MCP
Complete the connection before starting the hearing. For clients that require recreating the session after adding tools (e.g., ChatGPT (Web) — previous conversations are not carried over to a new chat. Environments that can resume a session, such as Claude Code, do not apply), because if you connect after the hearing, the agreements from 0-1 to 0-5, such as the role × screen permission matrix and the status transition table, will be lost with the conversation.
If connection becomes necessary midway no matter what,write the agreed content to a file before recreating the session. For the connection procedure itself, follow the admin-mcp skill.
If you do not have even one Kuroco site (cold start), site creation is required before connecting. references/create-site.md Create a site from the public API with , and proceed to 0-1 after completing the Admin MCP connection. Because creation involves OAuth consent and recreating the session,complete it exactly at this 0-0 (before the hearing)is included in the discussion.
0-1. Hearing
AskUserQuestion In environments where is available, confirm using selectable options. For the default behavior in environments where it is not available, refer to the "Default behavior when preconditions cannot be met" table.
The principle for how to ask is to "finalize the enumeration." Screens, roles, data, and states are faster to finalize bypresenting a draft enumeration from our side and having them correct the differencesrather than waiting for free-form answers (it is easier for the other party to look at a lined-up list and say "we don't need this / this is missing" than to write it out from zero). Take the draft fromreferences/feature-mapping.mdthe "presets by app type" in .
AskUserQuestion Since allows up to 4 choices per question, it is not suited to confirming enumerations. For enumerations, present a draft in text, and use selectable options for binary decisions (device policy, framework, publication method, progression pattern).
| # | What to ask | Format | Things that get stuck if not decided | Handling in small-scale, simple projects |
|---|---|---|---|---|
| 1 | Purpose of the app and scope of work(From where to where it will be centrally managed) | 1-2 sentences | The scope diverges and the enumeration of screens/states never ends | Required |
| 2 | Application type(Blog / Corporate / Membership site / List+detail type / Internal business system / EC …) | Optional | Pattern determination of 0-2, preset selection | Required |
| 3 | Enumeration of user rolesと、Visible scope per role(All records / Only those created by oneself / Only one's own department or site / Only those assigned to oneself) | Bullet points | Member group design, screen display switching, authentication methods of 0-5,Condition columns of the permission matrix of 0-3(If record-level restrictions are not asked here, they will be guessed in the deliverables) | Required. However, if there is only one role, a single line "Only 1 type, no restrictions" is sufficient |
| 4 | Enumeration of screens(numbered) and,Entry point per role(The first screen landed on after login / from the top)・Main user flows(How a representative task is completed by traversing screens) | Bullet points | Endpoint granularity (3-1), routing, navigation design | Enumeration of screens isRequired. If there are few screens and the flows are obvious, collapse the entry points and flows into a single line "Top only, flows obvious" |
| 5 | Enumeration of data handled and parent-child relationships(Whether one record has multiple details. Detail items and expected number of rows) | Bullet points | TopicsGroup splitting and how details are held (2-2) | If it is clear from the request text that there are no details, collapse into a single line "No details" |
| 6 | Enumeration of states (statuses) per data | Bullet points per data type | How states are held (0-3), list filtering, necessity of approval functions | Required(If the states are only "public/private", write that as well) |
| 7 | Types and purposes of attached files | Bullet points | file / image Number of fields and how multiple attachments are held |
If the number of files is fixed in the request text, collapse it |
| 8 | Required functions(Login, search, favorites, comments, inquiries, graphs, change history…) | Bullet points | Mapping table of 0-3 | Do not enumerate functions not in the request text; close with a single line "Not adopted" |
| 9 | Expected scale(Number of users, number of data records/year) | Numeric values | Pagination, cache, and traffic design | If stated in the request document, confirm; otherwise, place a provisional one-line entry |
| 10 | Device policy(PC-centric or not. Which screens are used on mobile?) | Selection + target screens | Framework selection (1-1), review scope | If there are few screens and full-screen responsive is sufficient, collapse into a single line of "full-screen support" |
| 11 | Design policy and UI patterns to use(tones, sidebar, badges, tables, graphs, timelines…) | Bullet points | Phase 1 implementation instructions. If raised later, each screen will need to be rebuilt | Place provisionally and move to confirmation items (does not affect the design skeleton) |
| 12 | Demo/sample data requirements(For one representative item, include concrete values) | Bullet points | Input content for 2-4, persuasiveness of the review | Place provisionally and move to confirmation items |
| 13 | Planned integration with other systems(Integration destination and data direction: fetch only / send only / bidirectional) and,External service dependencies that are not easily recognized as "integrations"(Payment, maps, email delivery, existing authentication infrastructure/SSO, etc.) | Selection | 0-4. If none, explicitly state "no integration" and proceed | If not stated, confirm as "no integration, no external dependencies" and collapse |
| 14 | Framework/release method | Selection | 1-1 / 4-3. If unspecified, select using the criteria in 1-1 | Apply the criteria and confirm (do not collapse) |
It may be collapsed according to the "Handling in small-scale, simple projects" column. However, the fact that it was collapsed must be written in the deliverable(One line such as "#5 No details (a single article is self-contained)").Silently omitting is different from collapsing because the conditions are met. Items marked "required" should be confirmed regardless of scale—the rework when discovered later is asymmetrically large.
Conversely, do not leave something provisional when it does not meet the conditions for collapsing. The item below, "Do not proceed while the granularity of enumeration remains coarse," is the guard against that.
Ask about states (statuses) separately for each data type. In business processes with consecutive steps (application → order → inspection → invoice matching, etc.), there is not just one state machine but multiple. If mixed into a single enumeration, the actor that moves the state and the data that holds the state become misaligned, and it will have to be broken down again later.For each state, ask up to "who," "by doing what," and "where it goes next"—this directly becomes the status transition table and role permission matrix in 0-3.
Do not proceed while the granularity of enumeration remains coarse. Don't stop at the "approval feature"—work it down to "how many approval stages / who approves / where does it get sent back to." If you build the screens while this is still ambiguous, you'll end up redoing them in the Phase 1 review. For items whose granularity can't be pinned down, put a provisional enumeration andthe scope of impact if it deviatesas a single line in the confirmation items (same treatment as the "default behavior when the premise can't be met" table).
0-2. Deciding the proceeding pattern
Based on the hearing in 0-1, decide here whether to proceed with A/B/C.State the decision and the reason clearly in the Phase 0 deliverables.
First, check the user's request content and attached materials themselves. If the schema/column definitions, the existing DB's CSV, the migration source site's API response examples, etc. have already been provided, they themselves become the basis for "data model finalized."In this case, there's no need to ask about the degree of finalization again in 0-1—only ask when it can't be read from the request content.
| Axis | State | Choice |
|---|---|---|
| Data model finalization level | Not finalized / want to solidify from the screens | → A |
| Existing data structure in the request content / nearly finalized / standard replacement | → B | |
| Frontend owner | I (this session) implement it | A or B |
| Another team implements it | → C |
Complexity (number of screens, number of content types, presence of authentication/payment) does not factor into the A/B/C choice itself. Even for a simple app, if the data model is not finalized, A is correct. Complexity matters for the chosen pattern'swhether the contents can be compressed—if simple, the mapping table in 0-3 may be put in a simplified form, but the authentication method decision (0-5) and the Admin MCP scope confirmation (0-6) must not be omitted regardless of complexity (because the cost of noticing later is asymmetrically high).
| pattern | Order | Content |
|---|---|---|
| A Mock-first (default) | 0→1→2→3→4 | In Phase 1, create a mock in the form of a Kuroco response, and after the screens are finalized, build the content definitions and API |
| B Backend-first | 0→2→3→1→4 | Build the content definitions and API first. In Phase 1,call the real API directly instead of building a mock(adherence to the mock contract and the Phase 4 switching procedure become unnecessary) |
| C Out of scope (deliver the API specification) | 0→2→3 | The frontend is built by another team. Phases 1 and 4-1/4-2 are not carried out. For details, see"When an entire phase is out of scope"refer to |
If the user is unsure about the order, confirm: "Do you want to see a working screen first, or do you want to solidify the data design first?"
0-3. Feature-to-Kuroco feature mapping and role/state design
Map each feature of the app to Kuroco's standard features.Before custom implementation, always check whether standard features can cover it.
| App features | Kuroco features | What to create |
|---|---|---|
| Data list/detail display | Content definition (TopicsGroup) + Topics API | Content definition,list/details endpoint |
| Article classification/filtering | Category (TopicsCategory) / tags | Category/tag settings,filter query |
| Option master (prefectures, etc.) | Table data (CSV table) | CSV table + csvtable field |
| Multiple line items per record (application details, product variations) | Repeating field group / JSON item / separate content definition + relation | Choose based on the expected number of rows (the decision is made in /kuroco-content-structure design decisions) |
| Multi-stage application/approval (with send-back) | Approval workflow (Approvalflow) | Workflow settings + Topics::waiting_for_approval_list / accept / reject endpoint |
| Status management of business processes | select status items + filter |
Status items (searchable: true) and filter parameters for the list |
| Change history/audit log | Content change history / dedicated content definition for logs | Topics::history_list endpoint, or content definition for recording + trigger processing (/kuroco-server-processing） |
| Login/member registration | Member + authentication (Cookie / Token) | Authentication-related endpoints (login_challenge, token, profile） |
| Favorites | Favorite | Favorite::insert / delete / list endpoint |
| comment | Comment（Activity） | Comment::insert / list endpoint |
| Inquiry/submission form | Form (InquiryForm) | Form definition + InquiryMessage::send endpoint |
| Keyword search | Topics search (topics_keyword / filter） |
list endpoint parameters |
| Payment/points | EC features (Stripe, etc.) | /kuroco-docs Refer to the corresponding tutorial |
Favorites, comments, and form submissions are standard features that can be configured either without login or for logged-in users. Do not assume "it's a members-only feature, so login is required"; specify clearly in this mapping table which one to use according to the requirements.
Detailed mapping table and design deliverable template: references/feature-mapping.md
Division of responsibilities(When the same table appears to be in two places, resolve it with this rule): The table above isSummary and judgment of frequently used features, and the "mapping table (detailed)" in feature-mapping is theauthoritative comprehensive list and references. The format of deliverables is authoritative in the "design deliverable template" offeature-mapping, and the body text (deliverables 1-4 in 0-3) definesthe requirements for what to include. If unsure about the format, follow the template; if unsure about which items to include, follow the body text.
Decide how to hold status
If it has been determined that the approval workflow will not be used (corresponds to "only progresses in one direction" in the distribution table below), you may stop reading this section there. Everything below (how rejections are handled, retrieval of in-progress application data, and the rules for composing the list) is for projects that use an approval workflow.
Assign the states listed in 0-1 to either the approval workflow (standard functionality) or a custom status field.If you build the screens without deciding this, the entire approval mechanism ends up being custom-implemented.
Do not judge the assignment by business vocabulary. Judge by "whether that transition involves a send-back (an operation that returns the item to the previous actor)". Japanese business vocabulary (confirm, review, route back, approve, finalize, check) can all be mapped onto phases of an approval workflow, so judging by vocabulary causes words with the same meaning to end up in different mechanisms from project to project.
| Transition type | Judgment |
|---|---|
| There is a rejection or send-back, andthe item is returned to the previous actor for resubmission(judging whether the content is acceptable) | A phase of the approval workflow. If multi-stage, one approval group per stage |
| It only proceeds in one direction (there is no return operation, or the return is not a "redo" but a kind of next step) | select one value of the status field |
| There is a return operation, butthe destination of the return is not a content revision before publication but a redo of the work(e.g., inspection send-back → in progress) | select one value of the status field. The approval workflow can only handle content approval before publication |
| Whether there is a send-back cannot be confirmed(not stated in the request text, and the user cannot be asked) | Default to "there is a send-back = approval workflow". Building it with an approval workflow and then reducing it to a status field is cheaper than the reverse direction (building it with a status field and then custom-implementing approval, send-back, and notifications).In the confirmation items, write the switch direction as "if there is no send-back, reduce by one phase / reduce to a status field"(the switching cost is deleting the workflow settings and revising the transition table, so it is not a design redo) |
| It changes with the passage of time rather than by an operation(accepting → acceptance closed → event ended, expiration of the publication period) | Do not create a status field; derive it from date/time fields（filter or a front-end determination). If you make it a status field, someone will end up switching it by hand, causing missed switches. Note: Do not cache long-term any endpoint whose filtering conditions include the current date and time(at date boundaries the cache diverges from reality). Either return all records and judge on the client side, or match the cache period to the granularity of the boundary. In the case of SSG, also decide the trigger for regeneration, such as a daily scheduled build |
Even when words are used differently, as in "the line manager confirms, and then the section manager approves",If both involve a send-back, a two-phase approval workflowand if the confirming side has no send-back (just passes it through), a single value in a status field.
| how to drop | content | cases it suits |
|---|---|---|
| two stages: approval + post-approval update | Topics::accept to finalize the content, and immediately after, Topics::update write the values decided with (transfer destination / assignee). On screen, make it look like a single button |
Send-back is also needed, and the values to decide are 1–2 items |
| Have the requester side provide candidates, and let the approver just choose | Have candidates (1st–3rd choice) submitted on the request form, and the approver selects one of the candidates and approves | Work where the requester can provide candidates |
| Don't use an approval workflow; use a status field | Have "awaiting assignment → assigned" as a status field, and make the assignment operation =Topics::update Topics::update |
When send-back (returning to the previous actor to resubmit) is not actually needed |
Write which one was adopted in the transition table in 0-3, and clearly state that this choice also affects the permission matrix (the meaning of the approval row) and the screen's action definitions.
| nature of the status | How to hold it in Kuroco | Notes |
|---|---|---|
| Content'spre-publication approval(draft → request → approval (multi-stage) → send-back → reflection) | approval workflowFor requests, pass Topics::insert / update に approvalflow_id The pending-approval list is Topics::waiting_for_approval_list, details are waiting_for_approval_details, approval is Topics::accept, send-back is Topics::reject(all are operations that can be created as endpoints) |
Multi-stage approval groups, approver specification (group / member / custom member filter), send-back destination selection, withdrawal, and email notifications to approvers are all available through configuration alone. Old Approvalflow::review / list_pending is deprecated |
| public approvalbusiness processes that follow after(ordered, partially inspected, inspection complete, invoice under review, payment on hold, completed, etc.) | select status items + transition rules are held on the front-end/custom processing side. Filtering in the list is filter, display is via status badges |
The approval workflow is a feature that expresses only approval of "whether it may be published" and cannot express the progress of the process. Do not mix them; separate them |
| simple public/private, draft only | Topics standard publication settings (open_flg） |
do not create status items |
-
For status items,
searchable: trueappend(always used when filtering the list. See 2-2). -
"Draft (an unsubmitted state visible only to the person themselves)" can be expressed by Topics' intermediate save (
Topics::draft_save/draft_list/draft_details). Whether to have a "draft" in the status items is decided bywhether drafts are shown in lists and aggregations(if shown, status items; if not shown, intermediate save). -
The operations of the approval workflow areapprove, send back, withdrawの3つ。There is no operation corresponding to "reject (a terminal state that prevents reapplication)", so if needed, hold it on the status item side(send back is an operation that returns to the applicant and is not terminal).
-
However, it is not possible to write "rejected" into a status item while it is still under application. A new application does not yet exist as content (
Topics::updatethe target oftopics_iddoes not exist), and in the case of an update application,updateapplies to the published version, not to the application content. Therefore, realizing rejection is limited to the following two ways, anddecide which to adopt in 0-3 and write it in the transition table:- Send back → the applicant withdraws(withdrawal is terminal. The application content remains as intermediate save data). If there is no need to show "rejected" in lists or aggregations, this is sufficient
- Once approve all phases and reflect it in the content, then immediately update the status item to "rejected". If you want to show rejected counts or rejection reasons in lists or monthly aggregations, use this (this amounts to organizing it so that approval is an operation that "finalizes the content" and the judgment of whether it is acceptable is held on the status item side)
This choice affects three deliverables: ① status transition table (expression of terminal states) ② permission matrix (in option 2, the "approve" row comes to mean rejection as well) ③ screen action definitions (whether the buttons are "approve/send back" or "approve and proceed/finish as no repair needed"). Do not fix only the transition table and leave the others alone.
-
What to put into the process status when approval is complete is expressed by the "initial value" of the status item. Since the application content is reflected in the content the moment all phases are approved, if the initial value of the status field is set to the beginning of the process (such as "Unassigned" or "Pending assignment"), it will be reflected with that value.Do not write trigger processing that detects approval completion and writes the status field— that itself amounts to "writing the synchronization processing between the approval workflow and the status field yourself."
-
In-progress application data cannot be obtained from
Topics::list. The in-progress data of the approval workflow is on a separate track from published content,Topics::listThere is neither an approval status parameter nor a response field inTopics::waiting_for_approval_list（get_workflow_info(enabling causes workflow information to be attached to the response), and the details are obtained withwaiting_for_approval_details.When all phases of approval are completed, the application content is reflected in the content andlistappears in . -
Enumerate "storage location → retrieval operation → whether it can be shown in the front-end list" for each status track before writing the composition rules. The number of compositions is not fixed at two:
track storage location retrieval operation how to show it in the list after approval completion (has a status field) content body Topics::list/detailsCan be shown as is. The badge is the value of the status field in progress (awaiting approval, in the middle of multiple stages) in-progress area of the approval workflow Topics::waiting_for_approval_list/waiting_for_approval_details（get_workflow_infophase information is attached with )Can be shown. The badge is the phase name unsubmitted draft in-progress saved data Topics::draft_list/draft_detailsCan be shown.Whether to include it in lists and aggregations is decided by requirements(if not included, it may be left as in-progress saved data) withdrawn application remains as in-progress saved data(explicitly stated officially) Topics::draft_listcan be treated as a "draft that can be resubmitted" returned application remains within the workflow and moves to the return destination (applicant / intermediate phase / another workflow).Unlike withdrawal, it is not stated that it "becomes in-progress saved data" waiting_for_approval_listDesign on the premise that it is visible on the side, andverify only this one point on the actual machine in phase 2(if it is not visible, fall back to a design that prompts resubmission via a return notification email, and do not hold it twice in the status field)depending on the result of verification on the actual machine -
thereforeif you show "awaiting approval" and the business process as one badge on the list screen,
listとwaiting_for_approval_listCall and combine the twoThere is a need. Conversely, if the design keeps approval operations confined to the admin screen and shows only published data on the front end, then combining is unnecessary, and in that case it is enough to write one line in the deliverable saying "combining unnecessary" and why (do not bloat the design by writing unnecessary combination rules). These combination rules (which takes priority, whether records under approval are mixed into the list, how the count badge is counted) are decided in phase 0.If you proceed to phase 1 without deciding, the design will collapse into holding the approval state redundantly in a status field as well, and you will end up writing the synchronization processing between the approval workflow and the status field yourself. -
When using the approval workflow, the "requires approval" in the permission settings isdisplayed only for groups whose user type is "editing user". Since the applicant and approver groups will be designed with the editing user type,if you do not want to show the admin screen in a business application, also use "admin screen unavailable"(for a deeper dive into group design, see
/kuroco-auth-design, and for the audit perspective, see/kuroco-security-auditD6・D7）。
Create a role × screen permission matrix
With the roles enumerated in 0-1 as columns and the screens (or operations) as rows, fill in whether viewing/creating/updating/approving is allowed. Without this, the endpoint access restrictions (0-5, 3-2) and the front-end screen display switching become ad hoc.
Rows consisting only of "screen" are not enough. Restrictions at the record level, such as "only one's own applications are visible" or "only one's own department's are visible," cannot be expressed at the screen level, so add the condition to the relevant row (for a deeper dive into scope design, see /kuroco-auth-design）。
Once you write the condition, write the "implementation mechanism" next to it. There are three types of record scope, andeven a single row that looks the same can differ by orders of magnitude in implementation cost. If you do not write the mechanism, that difference is not visible at the point of agreement.
| Type | Example condition | Implementation mechanism | Cost |
|---|---|---|---|
| Ownership type(created by oneself) | Only one's own submitted applications / only one's own reservations | Topics::list / details In my_own_list(the "filter by one's own content" parameter).self_only is a different thing, anddraft_list／draft_save／waiting_for_approval_list／waiting_for_approval_details parameters such as relation exist as properties of type fields(cannot be used for filtering the content list) |
One parameter. Standard feature |
| Attribute type(matches one's own affiliation) | Only one's own department / only one's own site / only one's own classroom | Category-level group viewing restriction (simple if the classification is fixed and few), or member extension items + MemberCustomSearchAuth | Settings only. The scope of standard features is /kuroco-auth-design 4. Confirm in |
| Assignment type(assigned to oneself by another person) | Only the work assigned to oneself / only the items one is responsible for | my_own_list も self_only cannot be used either because it is creator-based determination(the assigned side is not the creator). The minimal alternative implementation ison the endpoint side, filter custom processing that inserts the logged-in member ID as a fixed condition into（/kuroco-server-processing）。must not be substituted by front-end filtering— other people's records end up in the response and can be read from DevTools |
Custom implementation. State it explicitly as man-hours |
Although the assignment type is the most frequent in business applications, there is no straightforward receptacle for it in standard features. If the requirement is "only the assignee can see / operate it," leave that linein the permission matrix as requiring customization(without dropping the requirement, make the man-hours visible). Similarly, "show only posts by members of the same group" is not a standard feature either.
Deliverables: Present the following 4 points, and proceed only after obtaining the user's agreement. The template isreferences/feature-mapping.md. For handling in environments where agreement cannot be obtained, refer to the "Default behavior when preconditions cannot be met" table.
- A correspondence table of screens ↔ endpoints used ↔ content definitions/fields.Write the "implementation owner" (front-end implementation / Kuroco admin panel) in each row——If the number of writers is small and they can use the admin panel, first consider the option of not building post/edit/approval screens on the front end. If you do not build them, the endpoints (
insert/update/approval-related/authentication-related) and the authentication design become unnecessary all at once, and for small-scale projects the design becomes less than half. In that case as well, write one line saying "writing is done in the admin panel" so that the writing method does not appear to have been omitted from the design.This choice is a binary choice per screen, with no middle ground. For screens written as "front-end implementation," both reading and writing (create, update, delete, approve) for that screen, as well as output (CSV, etc.), areall connected from the front end to the real APIThis means that. "The screen exists but the operation button remains disabled" is not accepted as a deliverable—if only writing is to be shifted to the admin panel, write that operation's row separately as "Kuroco admin panel."Each row of this table becomes the source for cross-checking in 3-4 (endpoint coverage verification) and 4-5 (connection status table)so write it at a granularity (screen × operation) that cannot later be reinterpreted as "no corresponding feature" - Permission matrix of roles × screens (+ record-level conditions)
- A status transition table for each data item (state, role that transitions it, triggering operation, next state, storage method), andDefinition of the status display shown in the list. If you use both the approval workflow and status items, andshow data under application in the front-end list, then
listとwaiting_for_approval_listWrite the composition rules for .If not applicable (approval is confined to the admin screen and the front end shows only published items / no approval workflow is used), "no composition needed" + one line of reason is sufficient - Data model parent-child relationship (presence of details and expected number of rows. The decision on how to hold them is passed to the design decision in
/kuroco-content-structurepass to the design decision)
For all four points, if not applicable, consider them satisfied by "not applicable + one line of reason." Do not output an empty table. In a lightweight app, some items will actually be not applicable — for example, for an app with no details, item 4 is one line saying "no details (a single article is self-contained)"; for an app with only one role, item 2 is one line saying "no differentiation because there is one role."Write that the escape hatch itself was usedis the purpose, and it differs from omitting it and staying silent.
0-4. Determining the external system integration pattern
If integration plans have already been confirmed in 0-1, decide which pattern to use for each integration destination.If there are multiple integration destinations, you may choose individually for each(patterns may be mixed within one app). If there is no integration, state "no integration" in the deliverables and proceed.
| Pattern | Configuration | Suitable cases | Implementation reference |
|---|---|---|---|
| Direct call | The front end directly calls the external system's API. Kuroco is not involved | The external API side has already allowed CORS, the key may be placed on the front end, and real-time behavior is the top priority | Front-end only (no work on the Kuroco side) |
| Proxy (via Kuroco) | The front end calls a Kuroco custom endpoint, and within that Smarty template, {api} call the external API from the plugin and return the result |
You want to hide the external API key, centralize authentication/CORS/rate limiting on the Kuroco side, and process/compose the response | /kuroco-server-processing（{api} plugin) |
| Ingestion | Structured data (external API) isbatch processingperiodically{api}retrieved with{api_internal}and inserted into Topics with. Unstructured data (web pages/files) isspidercrawls and ingests. One-off events that require immediate reflection are received withWebhook/trigger email address. All are provided via the standard Topics API |
Low update frequency, you want to put external data also on Kuroco's standard features (cache, search, categories, multilingual), the external system is unstable or slow | /kuroco-server-processing(Batch processing, spider, trigger) |
Decision criteria (the correct one is /kuroco-server-processing 's "External System Integration Method Design". The following is a summary of it):
- Does the key need to be kept secret? → If yes, use a proxy or ingestion. Direct calls allow the key to be read from the frontend JS, so they cannot be used for private keys
- Is real-time capability required? → If required, use a proxy; if acceptable, use ingestion
- Do you want external data to also be available in Kuroco's standard features (search, categories, cache, multilingual)? → If you want that, use ingestion
- Spiders are not suitable for polling structured APIs(for crawling and ingesting web pages and files). If you are periodically fetching a structured API, use batch processing even for ingestion
Add the selected pattern to the 0-3 mapping table for each integration destination. If you choose proxy or ingestion, creating the endpoint in Phase 3 will require custom Smarty processing instead of the standardTopics::list/details, so custom Smarty processing is required (see 3-1). For deep design decisions per integration destination, such as authentication method, rate limits, timeouts, and where secrets are stored, use /kuroco-server-processing 's "External System Integration Method Design" and its deep-dive materials.
0-5. Determining Authentication Method and Reachability Path Restrictions
The configuration work is in Phase 3, but the decision is made here. The necessary inputs (whether member functionality is present and the domain configuration of the frontend and API) are in place at 0-1, and because this decision affects endpoint design, CORS, and the frontend implementation method, postponing it will cause rework. The same applies if you switch to backend-first.
There are two decisions in this process. Do not mix them.
| Decision | Question | Means |
|---|---|---|
| ① Authentication method(identity) | To whomShow it. Is it necessary to identify the user? | No authentication / Cookie authentication / Dynamic access token / Static access token |
| ② Reachability path restriction(network boundary) | From whereCan it be accessed? | API IP address restriction / KurocoFront delivery IP restriction and Basic authentication / No restriction |
"I want it visible only from within the company" or "I want it visible only to relevant parties" cannot be expressed by ①; they fall under ②. If you decide only ① and proceed, an internal-only requirement turns into a design of "register as a member and distribute accounts to all employees."Even if ② is "no restriction," state it explicitly in the deliverables(because otherwise it becomes impossible to distinguish whether there is no restriction as a result of a decision or because it was not considered).
① Authentication method
| Condition | Authentication method |
|---|---|
| Public content only (no membership features) | No authentication + cache |
| With membership features + frontend and API can be placed on the same parent domain | Cookie authentication |
| With membership features + cross-domain SPA (domains cannot be aligned / want to avoid Safari restrictions) | Dynamic access token authentication（X-RCMS-API-ACCESS-TOKEN header) |
| Server-to-server communication and provision of public information only | Static access token.Do not use for non-public data such as member information(The token string can be externally viewed from communication or JS) |
tips: Design the public scope and default permissions first, then choose the authentication method
Ultimately, in Phase 5, /kuroco-security-audit settings will be inventoried, but resolving this perspective beforehand reduces rework. Since the API is basically the entry and exit point for all data,first decide "is this data content that may be made public" on a per-content and per-endpoint basis, and thenchoose the authentication method and API security method (none / static token / dynamic token / Cookie) from the table above.
- Endpoints whose security method is
none(no authentication) must be verified to ensure that all data passing through them is public information. - A privileged static token (
privileged_static_token) is equivalent to indefinite logged-in credentials, and the impact of a leak is greater than that of a normal static token. Limit it to truly necessary uses, and do not use it carelessly(for details, see/kuroco-security-auditChecklist A2b). - If the approval workflow has members submit their own requests, the default ② below cannot be applied. The "Approval Required" setting is displayed only for groups of the editing user type, so the requester group must be created with the editing user type. In this case, combine ① (creation permission limited to the target content definition) + **"Admin Panel Unavailable"**, andverify on an actual machine in Phase 2 whether the scope limitation actually works. For posts, applications, and reservations that do not use an approval workflow, ② is the default.
- If there is a requirement for members themselves to create records (posts, applications, reservations), design the initial group's permissions using the following two options. ① Give the initial group creation permission limited to the target content definition (whether the scope can be limited is verified on an actual machine in Phase 2) ② Do not give the initial group editing-related permissions, andcreate records through custom processing of a public endpoint (
{api_internal}call an internal endpoint)（/kuroco-server-processing）。The default is ②—because giving members editing-related permissions requires verifying every time whether they can write to content outside the target scope. - The permissions of the group assigned by default at member registration are a particularly important checkpoint from a security perspective. First identify whether the admin screen is needed and whether content update permissions are needed, and if not needed, set it to "admin screen unavailable." If it is a member site where content updates are not allowed, keep the initial group equivalent to a "logged-in user" with no editing permissions (for details, see
/kuroco-auth-design2., and for the audit perspective, see/kuroco-security-auditchecklist D6).
Workarounds for the third-party cookie issue are /kuroco-frontend-integrationand for configuration details, see /kuroco-api-content .Record the decision result in the Phase 0 deliverables.
(2) Restricting the reachable route
| Requirement | Method | Configuration location |
|---|---|---|
| Only from the internal network (office/VPN)Can call the APIMake it so | IP address restriction per API | Admin screen [API]→[Security]→[IP address restriction], or the API settings in Admin MCP. The specified formats are individual IP, CIDR (192.0.2.0/24) and range (192.0.2.1-192.0.2.2). For multiple locations, create IPSETS_* in [Environment settings]→[Constants] and reference it with [[IPSETS_OFFICE]] refer to with |
| From the same rangeAlso the front-end screenMake it inaccessible | KurocoFront の ip_restrictions(if necessary, use basic Basic authentication) |
kuroco_front.json. The Basic authentication password is stored in plaintext, so do not put it in a public repository |
| Do not restrict (public site) | None | State "no restriction" explicitly in the deliverables |
- Do not block only the API side and leave the front end accessible. Even if the data is blocked, the screen structure, its existence, and build artifacts can be read externally.If the requirement is internal-only, block both within the same range(for details, see
/kuroco-api-contentIP address restriction,/kuroco-frontend-integrationのkuroco_front.json）。 - When per-API IP address restriction is configured, the cache is generated per client IP. Because the cache is split by the number of allowed IPs, the hit rate drops when there are many locations or VPN exit IPs (with a single NAT exit, it is effectively one). For designs operated with no authentication + caching, write this side effect in the deliverables.
- Viewing restrictions are evaluated from the top down: per-API IP restriction → per-endpoint → per-content definition → per-category → individual content. If denied at a higher level, it is denied regardless of lower-level settings.
- IP restriction is not a substitute for identity. Because everyone on the same network can see the same data, if you need "who viewed it" or "show only that person's data," choose member authentication on the (1) side.
- Even if ② is "unrestricted" (public site), publication happens only after the user explicitly says so. Until then, deploy with the non-public default (robots.txt
Disallow: /+ Basic authentication/IP restriction) (applied in 4-3. For details, see/kuroco-frontend-integration"Non-public default").
If a design that goes beyond these four options is required—such as member group design, registration flow, content access restriction scope, password policy/two-factor authentication, or proxy login—use /kuroco-auth-design .
0-6. Confirming the connection target site and build constraints (Admin MCP)
Writes happen from phase 2 onward, but confirmation is done here. Insufficient scope is succeeds up to content definition creation (2-2) and fails for the first time at endpoint creation (3-1), so by the time it is noticed, a half-created content definition remains.
Scope is not the only thing to finalize in this step. whoami In a single call to , the values that constrain subsequent design decisions are returned all at once.If you overlook the returned values, you may discover in phase 2 that the design decided in phase 0 cannot be built.
① First confirm the target site (before scope confirmation)
There is no guarantee that there is only one connection. In an environment where multiple Admin MCP servers are connected,whoami being able to call does not mean "information about the build target was obtained." Proceed in the following order:
- Enumerate connection candidates (if there are multiple, list each one's
whoamiのsite.site_key/env) - Confirm one target and write the basis for it in the deliverable(specified in the request / it was the only connection / confirmed with the user)
- Take values from the confirmed target
Decision order when confirmation with the user is not possible and multiple candidates remain(apply from top to bottom, and stop once a decision is made):
- Eliminate candidates that cannot satisfy the requirements. The judgment material is
permissions.granted/permissions.deniedとpermissions.connection.scope。Required permissions are back-calculated from the mechanism chosen in 0-3 and 0-4—if creating a member group, thengroupwrites; if creating an aggregation batch, thenbatchwrites; if creating an endpoint, thenmcp:tools.allor higher (creating member groups and general-purpose Smarty batches requiresmcp:admin).If 0-3 is still provisional, it is fine to back-calculate while it remains provisional(if the mechanism changes later, redo this judgment). envがprodPrioritize candidates that are not(to avoid accidental impact on production).If all candidates areprodskip this step—then, if the adopted candidate isprodeven if write permission is explicitly granted, make completion ofEven if write permission is explicitly granted,site-backupa prerequisite for writing.site_backup-listでready=true) as a precondition for writing. Write that fact in the confirmation items as well- Prioritize candidates that match the request context (e.g., the site key or connection name matches the target project name)
- If it still remains,provisionally adopt the first candidateand write "the candidate list, the rationale for the choice, and the scope of impact if it is wrong" in the confirmation items
If you write the decision and its rationale in the deliverable, the material for judging whether to replace it later remains.
If the request does not specify a site and there are multiple candidates, or if it was site.env が prod(production), thenwrite that fact in one line in the confirmation items(the scope of impact if it is wrong = all the constraint values in the table below change, and you will have to re-determine how to divide and classify the content definitions and how to hold the details). You may provisionally choose one and proceed, butyou must finalize it before writing in phase 2。
② Confirm the scope
permissions.connection.scope Confirm:
| Effective scope | Handling in this skill |
|---|---|
mcp:admin |
No constraints |
mcp:tools.all |
Normal construction is possible. Only creation, modification, and deletion of member groups and general-purpose Smarty batches, granting of superuser groups, and issuance of privileged static tokens are not allowed |
mcp:tools.write or below |
Cannot create endpoints. Do not start construction |
If it is insufficient,do not call tools on guesswork to confirm failures.
whoami の permissions.connection.available_scopes present it and request reauthorization at the required level.
mcp:admin can only be obtained by a superuser, so if the other party is not one, guide them to mcp:tools.all .
If not connected, follow "default behavior when preconditions cannot be met," andstate the required scope explicitly in the deliverableand then proceed with phase 1 (mock construction). Be sure to resolve it before starting phase 2.
For the breakdown of scopes and their correspondence to permission modules, refer to /kuroco-admin-mcp .
③ From the same whoami read the construction constraints and transcribe them into the deliverable
Do not look only at the scope and move on. The values in the table below directly constrain the design decisions in 0-3 and 2-2.If you design without reading them, you will discover at creation time in phase 2 that "it cannot be created due to a limit" or "the key names differ from what was expected."
| Fields to read | What is determined | Transcription destination |
|---|---|---|
site.site_key / site.env |
Identification of the construction destination.prod If so, before writing site-backup |
Beginning of the deliverable / confirmation items |
site.copy_from_site_key |
The copy source of this site(A Kuroco site is always created as a copy of something). The default for how to handle the settings inherited in 0-7 is determined.Some environments do not return itSo if it does not exist, treat it as "unknown" and fall back to 0-7 | 0-7 inventory table |
site.site_url / site.api_url |
Whether the frontend and API domains share the same parent.The decision input for the 0-5 authentication method itself(The default domain is …g.kuroco-front.app と …g.kuroco.app and the parent differs = Cookie authentication cannot be used) |
Reason for the 0-5 decision |
site.topics_ext_key_format |
Whether the extension item key is ext_<n>(position-dependent sequential number) or ext_col_<nn> か。regardless of which, setting ext_slug for all extension items avoids the impact |
2-2 field list |
site.limits.topics_max_extension |
The number of extension items that can be held in one content definition:current upper limit（{current, max}). If you count the items and exceed it, either split the definition or admin_setting-update raise it with |
2-2 field list |
site.limits.topics_ext_group_loop |
The current row count upper limit for repeating field groupsCurrent maximum number of rows. Basis for deciding whether line items and multiple attachments can be held in a repeating group | 0-3 parent-child relationship table |
site.limits.topics_contents_type_cnt |
The number of categories that can be set simultaneously on one content itemcurrent upper limit (ifcurrent: 3 then "up to 3 categories per record").It is not the total number of categories that can be registered, nor the number of classification axes—it is not a limit on how many categories can be created, so it does not lead to the decision "since there are only 3 slots, do not use categories" |
0-3 mapping table |
site.limits.member_max_extension |
Current upper limit for member extension items. Feasibility of a design that holds role determination and affiliation scope in member extension items | 0-3 permission matrix |
site.topics_ext_features |
can_use_number_field（number type is usable) /can_mark_field_searchable（searchable is usable) /can_import_structured_json。Do not design to use those that are false |
2-2 field list |
security.can_update_ip_restrictions / security.ip_restrictions |
Admin screen, Admin MCP, file deliveryfeasibility of IP restrictions and current status (only these three systems are returned).The IP restriction for the public API and the restriction for KurocoFront delivery are outside the scope of this field—the former is in the API security settings, the latter is configured separately in kuroco_front.json (0-5②) |
0-5② decision |
permissions.granted / permissions.denied |
Effective permissions per module.Decision material for eliminating connection candidates based on requirements(①), andmcp:tools.all even with mcp:tools.all, writes for group or batch may be dropped group や batch writes may be failing |
0-6① selection rationale |
permissions.connection.available_scopes |
Reauthorization level to guide when insufficient | Confirmation items |
The upper limits are returned as the pair {current, max} .current current is the effective value, andmax can be raised up to max with admin_setting-update admin_setting-update can be raised with（mcp:admin is required).current Since writes exceeding current are only discovered as rejected,Count the number of items and rows in phase 0。
current When it turns out that it does not fit within, the default is "current raise"（max Within the range up to,admin_setting-update). Changing the design side (splitting definitions, changing how classifications are held, extracting details into separate definitions) should be doneonly if you do not have the authority to raise it (mcp:admin is not the case) or if even after raising it max it exceeds. Before distorting the design because of a limit, first check whether the limit can be changed.
0-7. Inventory and disabling of inherited existing settings
A Kuroco site is always created as a copy of some site (a template site / a duplicate of an existing site). Every new site already contains the copy source's API definitions, endpoints, content definitions, categories, and member groups from the start, so "it's empty because nothing has been created yet" does not hold.Stop anything you will not reuse before starting construction. If you leave it until phase 5, you will not be able to distinguish what you created from what came from the copy source, and endpoints that inherited the copy source's authentication method, CORS, and tokens will remain in a public state.
Procedure
- Confirm that you are connected to the target site finalized in 0-6①. Disabling it on the copy source (which may be a live production site) causes real harm
whoamiのsite.copy_from_site_keyDetermine the copy source with(In environments where it is not returned, "unknown". Do not fill in with guesses) → Apply the defaults in the table belowapi-list→api_uri-list, the list of content definitions (Confirm the tool name with the actual name oftools/listconfirm by real name) and sort them into "reuse / do not reuse / decision pending", thenpresent them to the user. Put anything whose purpose you cannot understand in pending (keeping is safer than deleting).If the name remainsDefaultif it remains as isit is highly likely to come from a template, and if there is no corresponding purpose, you may set it to "do not reuse" without leaving it pending- Execute after approval, and write the sorting results (with reasons) in the deliverable. In the phase 5 audit, it can be cross-checked as "A7 was handled here"
Default handling per copy source
copy_from_site_key |
Default handling |
|---|---|
nuxt-auth-template |
Content definition id=1 と API id=1 overwrite and reuse(do not create new).API id=1 Existing endpoints underare deleted |
| Other than the above | Sort in step 3 |
| Not returned / unknown | Same as above. Write one line in the deliverable stating that the copy source cannot be identified |
For copy sources not in the table, do not guess the default. List them and have the user confirm the assignment.
Caution
- Disabling/deleting writes to Kuroco. Gate definitionObtain approval as specified (if not obtained, output only the inventory table and
[!], resumption condition "approval for the target").Default is disable, not delete——DefaultIf it can be judged to be template-derived, such as the name, and the contents are also empty, it may be deleted.envがprodIf it issite-backupMake completion a precondition - When disabled, all issued tokens for that API are also deleted. Check whether there are any users of the inherited token by actual usage (
api_uri-listfor the last 8 days ofapi_analytics-list) before executing.DefaultA name is a clue, not evidence (it may have been renamed and used /Defaultmay still be used in production as is) - For content definitions that contain data, you may choose "do not repurpose but leave in place"(stopping it will break references). Write "unused (left in place)" in the deliverables, and carry over the same handling in phase 5
group_idMember groups of 100 or less are Kuroco basic groups.group_id = 1(Administrator) is depended on by standard features, so do not touch it.2From (Editor) onward, if unnecessary, they may be deleted, but there is no need to actively delete them just because they are not in the requirements- Copied tokens/secrets originating from the copy source are outside the scope of the build. Write anything noticed in the handover to the operator (audit perspective is
/kuroco-security-auditcategories D and E)
Phase 1: Build the frontend with mocks
Contents of Pattern A. In Pattern B (backend first), read this phase as "call the real API directly"—compliance with the mock contract (step 3) and switching in phase 4 (4-1) become unnecessary. Instead of field reverse engineering (step 5), use the fields and endpoints finalized in phases 2 and 3 as is. In Pattern C, you do not perform this phase.
Purpose: show a "working appearance" to the user as quickly as possible and finalize the screens.
Before screen implementation, /kuroco-frontend-integration Follow "Screen design and design implementation", decide the Kuroco/frontend management division, and apply the default design rules described in that section. For the mock review in step 4 and the real data display check in phase 4-2, use the confirmation viewpoints in that section.
-
Framework selection and project template: If not specified by the user, choose based on the app type
The judgment is made based on the conditions below, not the app's type name(If decided by type name, it will always be mis-selected in cases where the type is the same but the conditions are reversed, such as "an internal-only blog"). Look from top to bottom and take the first row that matches:
Judgment condition What to choose Reason Is SSR / ISR required?(There are many pages and the SSG build cannot keep up / the update frequency is high and waiting for builds is unacceptable).If SEO/OGP is the motivation, SSG is sufficient, so "not required". Member-only / authentication-required screens are also "not required"—Session cookies are not included in server-side fetch, so the advantages of SSR do not appear If required, Next.js / Nuxt SSR setup + Vercel, etc.. KurocoFront is static hosting, so it cannot be served The only technical reason the deployment destination falls outside KurocoFront. For the decision, follow /kuroco-frontend-integration's "How to determine whether SSR/ISR is truly necessary"Is it necessary for search engines to crawl it (Traffic is needed on the public site? If it is internal-only, authentication-required, or under IP restrictions, it will not be crawled, so "not required") If required, Nuxt 3（ nuxt generateでSSG）Static HTML is required. Official documentation and tutorials are also centered on Nuxt, making it easy to cite evidence If the above becomes SSG,Is there an operation in place to rebuild and redeploy every time content is added?(If the people updating are non-engineers and the update frequency is high, then not possible) If crawling is an explicit requirement, maintain SSG and achieve both by automating deployment(Content update trigger → GitHub Actions → automatic deployment to KurocoFront. For screens whose display changes by date, also add a daily scheduled build). If crawling is only "nice to have", then reduce to Vite + Vue 3（SPA） fall into SSG requires a rebuild every time one article is added, and if operators cannot deploy, "published but not showing up" becomes routine.However, if you drop to SPA, the first-row requirement (search traffic) is lost—you must not negate an explicit requirement in later rows. The implementation of automatic deployment is /kuroco-server-processing(trigger)Crawling is not required (member-facing tools, dashboards, internal systems, and authentication-required screens are the main focus) Vite + Vue 3（SPA） With the minimal configuration, there are no SSR pitfalls, and all fetches originate from the browser, so authentication is straightforward. vite build→dist/Can be served as-is via KurocoFront rewritesThe team assumes React Vite + React（SPA）/ Next.js（static export） Keep the answers to the above conditions and replace with a React-based option (static export if crawling is required, SPA if not).With Next.js static export, cookies()/ Server Actions / ISR cannot be used—constraints and workarounds, see/kuroco-frontend-integrationrefer toThe structure is
/kuroco-frontend-integrationfollow the project structure of . Because there is a pitfall in data fetching with SSR/SSG where session cookies are not included in server-side fetch, screens that handle authenticated content should be shifted toward SPA (client-side fetch).If device policy was narrowed down in 0-1 (e.g., PC-centric, with mobile only for application confirmation and approval),explicitly state the screens targeted for mobile support during review.Do not optimize all screens for mobile—if you spend effort on non-target screens, the review of the screens you want to finalize will be delayed
-
Insert one API client layer: Instead of fetching directly from UI components,
composables/useKurocoApi.ts（Nuxt）やlib/kuroco/client.ts(Next). Switch between mock/real API via environment variables -
Create mock data in the Kuroco response format: For lists,
{ list: [...], pageInfo: {...} }, for details,{ details: {...} }. Do not leave extension fields as raw key names (ext_1/ext_col_01), but convert them to application types with the client layer mapper (following the contract ofreferences/mock-contract.md )- Create the contents according to the demo data requirements heard in 0-1. If one representative case is specified down to concrete values (amount, count, number of attachments, etc.), use those values. This increases the persuasiveness of the review, and the contents of the sample content to be inserted in 2-4 will be finalized here.
- Include at least one of all status patterns. The badge, filtering, and transition button variations in the list cannot be checked without data for that status.
-
Screen implementation → Review: Start the development server and show it (or a screenshot). Reflect feedback,do not proceed to Phase 2 until the screen is finalized. For alternative acceptance criteria in environments where people cannot view the screen, refer to the "Default behavior when preconditions cannot be met" table.
-
Field back-calculation: List the items used in the finalized screens (title, image, date, category, etc.) and convert them into the field list of the Phase 2 content definition.Status items, detail row structure, fields for each attachment type, and items used for role determination (applicant, department, etc.) should also be included in the back-calculation targets—Although used for badges and conditional display on the screen, they are easily missed as fields
Why wait for screen finalization: Changing the content definition (adding fields, changing types) is more costly than creating it, and also involves modifying already inserted data. It is faster to finalize the necessary fields from the screen and then create them all at once.
Phase 2: Backend construction (Admin MCP)
Write operations (INSERT/UPDATE/DELETE) must always be confirmed with the user before execution.
- Connection check:
whoamiCheck the authentication status with the tool (Admin MCP), andtools/listcheck the tool list with . If not connected,/kuroco-admin-mcphave the user connect using the procedure in (OAuth recommended). For deliverables when proceeding while unable to connect, refer to the "Default behavior when prerequisites cannot be met" table - Content definition creation（For definitions decided in 0-7 as "overwrite and reuse", do not create new ones but update them。
nuxt-auth-templateIf copying from , the target isid=1): first,/kuroco-content-structurein Part 1 (design decisions) of , design the TopicsGroup splitting, master data representation method (CSV table vsrelation), how to hold classifications, andext_slugnaming based on the fields back-calculated in Phase 1. Once the design is finalized, follow Part 2 (creation with Admin MCP) of the same skill, build the JSON, and create it with thetopics_group-createtool. Before creation, always check the tool'sinputSchema（tools/list).Setsearchable: truefor items frequently used in screen search/filtering(displayed in the admin screen search form, and internally saved asext_limit_item.searchable=1. For the field list, refer to/kuroco-content-structure) - Categories, tags, masters: Set categories/tags corresponding to the screen's filtering UI. If option masters are needed, prepare table data (CSV table)
- Sample content insertion:
topics-createInsert several items with -type tools.Same content as mock dataBy doing so, you can confirm in the Phase 4 replacement verification that there is no screen difference. For multiple items, do them one by one, not in parallel - As needed: Member groups, authentication settings, form definitions, enabling favorites/comments, creating approval workflows (if an approval workflow was selected in 0-3. Create approval groups = approval phases for the number of stages, and specify approvers by group/member/custom member filter. The status transition table from 0-3 becomes the settings as-is). If the relevant tool is not visible in
tools/list, it may be due to insufficient scope (/kuroco-admin-mcprefer to the checklist). If there is no tool, guide the user through the setup procedure in the admin screen
Phase 3: API creation
- Endpoint creation: Create as per the screen ↔ endpoint correspondence table.Create for the API definition decided in 0-7 as "overwrite and reuse"（
nuxt-auth-templateIf copying from , APIid=1. Existing endpoints are assumed to have been deleted in 0-7)- Endpoints must explicitly specify public settings at creation time(do not rely on default values). After creation,
api-export_openapiconfirm that the endpoint actually appears with - Check whether Admin MCP has API definition-related tools with
tools/list(do not guess names; always confirm from the list) - If there is no tool, guide the user through the admin screen procedure ([API] → target API → [Add endpoint]) with concrete values for model, operation, and path (for details of the procedure, see
/kuroco-docsのtutorials/configure-endpoint) - For endpoints where the proxy/ingestion pattern was selected in 0-4, the standard
Topics::list/detailsis not used; custom Smarty processing is required. The proxy is{api}a template that calls an external API with the plugin and returns the result; for ingestion, first ingest into Topics using a batch, spider, or trigger, then return via the normal Topics API. Follow/kuroco-server-processingfor the implementation
- Endpoints must explicitly specify public settings at creation time(do not rely on default values). After creation,
- Security settings/cache settings: Apply the authentication method decided in 0-5and configure CORS (allow the frontend origin; for Cookie authentication,
Allow-Credentials). Do not decide the method again here—go back to the decision table in 0-5.For endpoints that do not require authentication and are updated infrequently, set the cache period to at least about 1 day (86400 seconds). For which range of cache is automatically cleared when content is updated, see/kuroco-api-content"Topics cache clear range"—note that the standard Topics API (list/details, etc.) is automatically cleared, but custom Smarty endpoints for proxy/ingestion patterns are not automatically cleared - Cross-checking with the mock contract（Pattern A only. Pattern B is out of scope because there is no Phase 1 mock at this point—in Phase 1, call the real API as-is): Match the values tentatively placed in Phase 1 to the real ones (actual key names and assignments for extended items, actual category IDs, API ID and path). Do not hide differences with a mapper;correct the mock side to match the real thing(to keep the mock a copy of the contract). The write-back destination is the single aggregated file decided in 4-4
- The source for cross-checking is obtained with the Admin MCP
api-export_openapitool. The OpenAPI 3.1.0 document for that API is returned, so cross-checking with the mock can be done mechanically- Input:
api_id(integer, required),format（json|yaml, defaultjson） - Read-only tool (available with the
mcp:tools.readscope). Write permission is not required - Only when supplementary information is needed, also use the read tools for content definitions and category lists
- Input:
- The response shape (
{ list, pageInfo }/{ details }) is a specification determined by model and operation, and should be checked in/kuroco-docs. It does not change from endpoint to endpoint - Do not use browser-based (Swagger UI/admin screen) procedures. Also in Admin MCP
Api::openapi_dataHowever, if there is information that cannot be read, inform the user of that fact and where to check it in the admin screen, then stop
- The source for cross-checking is obtained with the Admin MCP
- Exhaustive cross-check against the mapping table（Common to all patterns. This is also performed for patterns B and C): 3-3 is the step of matching the "shape" of responses to the mock, andwhether all endpoints listed in the mapping table existhas not been checked. Here, for the 0-3 deliverable 1 (screen ↔ endpoint mapping table), eachrowを
api-export_openapioutput (path × method) ofcompare row by rowand make the results into a table- The unit of comparison is "screen × operation." Not only list/detail (read) operations, butcount rows for create, update, delete, approve, and send back (write) operations and output (CSV, etc.) in the same table. Having only reads in place does not mean it is exhaustive
- Rows that are in the mapping table but not in OpenAPI are,unless 0-3 records "not to be built (Kuroco admin screen)," not implementedand return to 3-1. Do not skip them with "if the feature exists" or "add it later"
- Endpoints that are in OpenAPI but not in the mapping table are either omissions from the 0-7 inventory or leftovers from prototyping, so determine their purpose and either add them to the mapping table or disable them (same treatment as A7 in 5-2)
- Use this comparison result as-is for the "endpoint presence" column of the connection status table in 4-5; it also becomes the basis for the "list of endpoints built" passed to the audit skill in 5-1
- Why make it a separate step: Missing reads can be noticed because the screen becomes empty, butmissing writes look natural as "buttons that cannot be pressed" and are not discovered until the requester touches them. In pattern A, writes succeed at the mock stage by updating local state, so when switching to the real API, only reads break while writes are quietly left behind. Always run the existence cross-check once, separately from the "shape" cross-check
Phase 4: Real data connection and release
- switching（4-1）:
.envset Kuroco's API base URL (https://{site_key}.g.kuroco.app) in, and switch the API client layer from mock to implementation. Ideally, UI components are not changed - Read display check(4-1): Confirm that the same screens as with the mock are displayed with real data, and isolate the cause of any differences. Differences in data format are due to mistaken assumptions about the response shape, so absorb them in the client-layer mapper. Display breakage due to text length or missing images is fixed in the layout or shared components. Follow
/kuroco-frontend-integration's "Screen design and design implementation" for the check perspectives.This is the completion condition for reads, not the completion condition for phase 4—do not say "connection complete" just because the display is in place - Connection of write operations(4-2): In the mapping table, marked as "frontend implementation"Create, update, delete, approve, send back(writes) andoutput(CSV, etc.) and login/member registration (
/kuroco-frontend-integrationimplementation pattern. Be mindful of third-party cookie issues) to the real API- The completion condition is "execute each screen's write operation one at a time, and confirm with the Admin MCP read tools that a record is created (updated, deleted, or approval status changed) on the Kuroco side.". It is not enough that the button can be pressed and no error appears (for the reason, see 3-4 "Why make it a separate process")
- Output (CSV, etc.) does not leave records, so this confirmation method cannot be used. Confirm that the number of items and fields in the retrieved file match the actual data on the Kuroco side (
topics-listcount and values). Mock fixtures appearing as-is is the typical sign of a missed switch-over - The records used for confirmation are the sample content from 2-4, or one created specifically for this confirmation. Ask the requester whether to delete it after confirmation (deleting is a write, so include a confirmation)
- Rows that cannot be connected should not be left as disabled buttons. Go back to the mapping table in 0-3 and change it to "Kuroco admin screen," or leave it unconnected in the table in 4-5 as
[!]and write the resumption conditions
- Confirming the publication destination(4-3): The default is KurocoFront. Change it only if the user specifies Vercel / Netlify / Codex Sites, etc. For the decision rules and the confirmation points when choosing something other than KurocoFront (CORS allowed origins, cookie domain, custom domain, permanence of the public URL), follow
/kuroco-frontend-integration's "Deciding the publication destination" - Deploy(4-3): For KurocoFront there are two ways (detailed steps;
kuroco_front.jsonsettings are/kuroco-frontend-integrationsee)- Private by default: Until the user explicitly makes it public, deploy with robots.txt
Disallow: /and access restrictions. The access restriction should be chosen by the user before deployment—Basic auth (fixed IDkuroco、PWはkuroco/ random 8 characters (recommended) / user-specified) or IP restriction (both KurocoFront and APIwith the same range. The admin screen and Admin MCP do not need it because they have authentication; do not apply Kuroco Files file delivery IP restrictions at build time). At completion, present the URL, ID, and PW as a set of three, and when a publication instruction is given, remove the robots.txt and the restrictionsas a setand redeploy (for details, see/kuroco-frontend-integration's "Private by default") - Admin MCP direct deploy: zip the build output →
files-create_temp_upload_urlupload →kuroco_front-deploy. No GitHub repository needed and the agent can complete it. Firstis_preview: truepreview deploy with, andstage_urlAfter confirming with the user, deploy to production. Since deployment is asynchronous (queue submission),kuroco_front-historycheck the reflection with - GitHub integration: Admin panel [KurocoFront] → GitHub repository integration (build and deploy with GitHub Actions on push). When entering continuous operation, guide them to this.
- If only local verification is needed, present that fact and the startup procedure.
- Private by default: Until the user explicitly makes it public, deploy with robots.txt
- Rollback update(4-4): Write the actual values finalized in phases 2 and 3 back to the aggregation file decided in 1-2 (refer to the note immediately after the "Progress Checklist").
- Connection status table and completion gate（4-5）: Screen × operation (read/write/output) × whether connected Present the table as a deliverable. The format is references/feature-mapping.md "API Connection Status Table". The rows should be mechanically copied from the 0-3 correspondence table (do not reduce rows here).
- For each row, "endpoint exists" is the verification result from 3-4, and "connected" is from 4-1 (read) and 4-2 (write/output)the result actually executed and confirmed. Do not mark unconfirmed rows as "done". For not connected, write
×, and for out of scope (not to be built), write—. - If even one unconnected row remains, do not report completion. If leaving it, write the agreement (who and when) and reason for "not to be built" in that row, and set 4-2 of the progress checklist to
[!]and add the resumption condition. As with the security re-audit in 5-3,confirm that all items are complete and there are no issues before reporting completion - In the completion report to the requester, include this table as is. Do not report with just the sentence "Construction complete."
- For each row, "endpoint exists" is the verification result from 3-4, and "connected" is from 4-1 (read) and 4-2 (write/output)the result actually executed and confirmed. Do not mark unconfirmed rows as "done". For not connected, write
Phase 5: Final security inspection (mandatory)
Always complete the construction with /kuroco-security-audit . Whether the authentication method, CORS, permissions, and access path restrictions configured in phases 2 to 4 are in place as designed should be verified by reading the configuration values, not from memory.
Perform before production deployment(after the preview deployment in 4-3). If joining a project that is already published midway, inspect it while it remains published.
5-1. Executing the audit
The audit skill isread-only. The prerequisites asked in Step 1 should beprovided from our side(if not provided, it cannot infer and will be full of "needs consideration"):
| Information to provide | Source |
|---|---|
| Target site (production/staging) | 0-6 の whoami の site |
| Site premise (fully public/members only/internal) | 0-1、0-5① |
| Decided authentication method and access path restrictions | 0-5①②。Communicating "this was intentional" reduces false positives. |
| Publication destination and public URL | 4-3 (CORS determination materials) |
| List and purposes of the API definitions/endpoints created | The correspondence table in 0-3 and the verification results in 3-4.Explicitly state those for prototyping/verification |
5-2. Reflecting the findings
Return to the applicable phase and fix it. Since fixes involve writes,Gate definitionobtain approval as specified.
| Audit findings | Return destination |
|---|---|
| A1/A2 (authentication method differs from the design / static token for non-public data) | Phase 3-2. Return to the decision table in 0-5① |
| A3/A4 (development origin remains in CORS) | Phase 3-2. Narrow it down to only the actual public URL |
A5 (endpoint for members-only data None） |
Phases 3-1 and 3-2. Cross-check against the permission matrix in 0-3 |
| A7 (unused API/endpoints) | Phase 3-1. Disable anything created for prototyping/verification that is no longer used(This tends to accumulate the most during construction). The procedure and precautions are the same as in 0-7.If anything originating from the copy source appears, it is an omission in the 0-7 inventory |
| A6 (rate limiting) / A8 (API IP restriction) | Phase 3-2. Cross-check with 0-5② |
| B/C series (admin panel IP restriction, password policy, two-factor authentication) | Site-wide settings.Since this is outside the scope of construction, leave it in the handover to the operator |
| KurocoFront Basic authentication/IP restriction | Phase 4-3.kuroco_front.json の basic / ip_restrictions |
Do not drop findings that will not be fixed either. For "acceptable given the site's premises" and "awaiting the operator's decision," write one line stating the reason and the acceptor.
5-3. Re-audit after fixes
Re-run the whole thing. Configuration changes ripple to other items (changing the security method invalidates tokens, narrowing CORS causes the normal path for another origin to fail, permission changes affect other screens), so checking only the fixed items will cause you to overlook other findings created by the fix.Report completion only after confirming that all items are in place with no problems. If findings remain, report them along with the remaining findings and how they are being handled.
When the premises cannot be met
| Situation | Default behavior | Symbol |
|---|---|---|
| The audit skill cannot be read | Check only the items equivalent to A1–A8 using your own knowledge and explicitly state "unverified" | [~] |
| Setting values cannot be read because Admin MCP is not connected | Write out the inspection items and confirmation procedure, then stop.Do not write "no problems" for "not inspected" | [!] + "Admin MCP connection" |
| Approval for fixes cannot be obtained | Leave the list of findings and stop.Do not report "complete" while leaving findings unaddressed | [!] + "Approval of the revised content" |
Supplementary notes for patterns B and C
How to choose the pattern (A/B/C) is0-2. Deciding the progression patternsee. Here we supplement the operations after selection.
When an entire phase falls outside your responsibility
Rather than swapping the order,a phase falls outside your responsibilityThere are such cases. A typical example is pattern C (the frontend is built by another team); in this case, phase 1 (mock construction) and phases 4-1/4-2 (real data connection) are not performed by yourself.
- For the progress checklist items of the relevant phase, use
[-](out of scope) and,（担当外: フロントチーム）write the responsibility alongside.Do not delete the row - Among the 0-1 hearings, even if you do not implement the "screen list" yourself,do not omit it. The granularity of the endpoints (how many items to return in the list, what to include in the details) is determined by this. If you cannot confirm with the other team, place a provisional screen structure and
04_確認事項in the equivalent, write in one line the impact scope as "if the screen structure changes, the endpoint granularity also changes" - Since you do not do phase 1,the cross-checking of mock contracts (phase 3-3) is lost. Instead, actually call the created endpoint once, transcribe the returned JSON into the specification document, and verify it
- The exhaustive cross-check against the correspondence table (phase 3-4) does not fall outside your responsibility. As long as you are the one creating the endpoints, verifying whether each row of the correspondence table exists in
api-export_openapiis your completion condition. The highest rework occurs when, at the stage where the other team connects, it turns out that "there is no write endpoint." For the connection status table in 4-5, set the "connected" column to（担当外: フロントチーム）and fill in only the endpoint presence column before handing it over
When the API specification document is a deliverable
When "presenting the API specification document is the goal," it becomes ready for handover only after satisfying the following.
| What to include | Supplementary notes |
|---|---|
| Endpoint list (method, path, purpose) | api-export_openapi Also hand over the OpenAPI 3.1.0 as a machine-readable version |
| Response examples actually obtained by calling | Not guessed samples but actual responses.errors / messages Include the entire form including |
| Authentication method and the implementation required on the frontend side | The decision result of 0-5. If Cookie authentication, up to the necessity of credentials: 'include' whether it is necessary |
| Error response format | → references/mock-contract.md |
| CORS handover notes | If the other team's origin is undetermined,make it a placeholder and clearly state that "after it is determined, it must be added in the admin screen". Do not settle it by setting a guessed origin |
| Field mapping table (API items ↔ screen display) | Actual key names of extended items (ext_slug : include the slug if configured |
| Known constraints | Items not included in the response (such as scheduled publication date), cache, rate limits |
Whether to create a new API definition or piggyback on an existing API
- Add to an existing API: When the authentication method and CORS match the current requirements and it will be used from the same frontend
- Create a new API definition: When the authentication method differs (e.g., the existing one uses Cookie authentication, but you want a public API with no authentication this time).The security method is a per-API-definition setting, so if the method differs, you have no choice but to separate them
- Before deciding,
api-listcheck the existing API definitions and their security methods. Write the reason for the decision in one line in the deliverable - The candidates for piggybacking are only the API definitions judged as "reuse" in 0-7. Do not piggyback on an API whose purpose is unknown because it derives from a copy source (you may unintentionally inherit the authentication method, CORS, and issued tokens)
Anti-pattern
| Things you must not do | Reason / correct approach |
|---|---|
| Create a mock in some ad-hoc form dedicated to the screen | When swapping it out, you will have to rewrite every screen. Build it from the start in the Kuroco response shape (contract) |
| Create the content definition before the screens are finalized (Except when Pattern B is chosen） | The cost of changing fields is high. Work backward from the screens and create it in one go |
| fetch directly from a UI component | You cannot switch between mock and real API. Always put a client layer in between |
| Guess the Admin MCP tool name andcall it | Names are dynamically generated. Do not call with a name not in the list. However,listing it as a candidate in the design document/procedure document is acceptable(Before execution, tools/list verify against the actual name of inputSchema and cross-check with, and state this together) |
| Implement standard features (favorites, comments, forms, multi-step approval, etc.) yourself | First map them to Kuroco standard features using the mapping table.Application, approval, and send-back can often be covered by the approval workflow（0-3） |
| Entering Phase 1 while the enumeration of screens, roles, and states is still vague | You will end up rebuilding every screen during review. Present a draft enumeration, have the differences corrected, and finalize it in 0-1 |
| Mix the states of multiple data items into a single status enumeration | The entity that moves the states and the data that holds the states become misaligned. Separate the state machine for each data type (0-1, 0-3) |
| Execute write-type tools without confirmation | Always execute INSERT/UPDATE/DELETE after user confirmation |
| Leave APIs/endpoints created for prototyping/verification enabled and consider the task complete | Attack surfaces overlooked in the review remain. Identify them in Phase 5, and disable those not in use (disabling involves deletion of issued tokens, so insert a confirmation step) |
| Skip the security check and report "completed" | There is no guarantee that settings were applied as designed. Phase 5 is mandatory. If the check could not be performed, explicitly state "not checked" and stop |
| Report "construction complete" at the point reads can be displayed (write buttons remain disabled / write endpoints not yet created) | Missing writes do not appear on the screen (3-4 "Why make it a separate process"). Check each row of the correspondence table in 3-4 against api-export_openapi , execute writes one by one in 4-2 to verify, and report with no unconnected rows in the connection status table in 4-5. Do not skip 4-2 on the grounds of "if the corresponding feature exists"—the correspondence table determines whether it exists |
| Report results of verification that was not actually performed | Substantiate both "done" and "cannot be done" with output from actual execution.Do not send work back to the user based on environmental constraints you have not tested |
Related skills (delegation targets per phase)
| Skill | Phase used | Content |
|---|---|---|
/kuroco-admin-mcp |
2, 3 | Admin MCP connection, authentication, tool naming, troubleshooting |
/kuroco-content-structure |
2 | Design decisions for content structure (TopicsGroup splitting, master data representation, classification, ext_slug policy) → creation of content definitions (TopicsGroup), field type reference |
/kuroco-api-content |
3, 4 | Endpoint design, authentication method, CORS, filter queries, CRUD |
/kuroco-auth-design |
0 | In-depth design of member groups, registration flow, access restriction scope, password policy, etc. |
/kuroco-frontend-integration |
1, 4 | Vite/Nuxt/Next implementation patterns, authentication implementation, deciding the publication destination, KurocoFront deployment |
/kuroco-server-processing |
0, 3 | Design of external system integration methods (in-depth materials for the same skill: plugin specifications, secret management, timeouts, pitfalls in real examples), external API integration ({api}plugins), batch, spider, Webhook, triggers (ingesting external data, custom processing such as notifications) |
/kuroco-security-audit |
5 | Security setting check at completion (read-only). Cross-checking authentication method, CORS, endpoint permissions, unused APIs, IP restrictions |
/kuroco-docs |
All phases | Cross-search of official documentation (basis for tutorials and specifications) |