basercms5-claude-workflow-setup

baserCMS5 × Claude Code Development/Migration Workflow Environment Setup

When proceeding with baserCMS5 (CakePHP5) development/migration using Claude Code, propose the "best way to proceed environment"This is an entry skill for that purpose. Technical implementation/rewrite patterns are left to another skill (basercms5-plugin-development / basercms5-theme-development, common rules are left to basercms5-development and others), and this skillhandles only the procedure of how to proceed = design → permission organization → Auto mode → implementation.

★Major premise (the character of this skill)

The main purpose is to "have the user learn (teach them)": This skill is not for performing the work on the user's behalf, but for **"communicating and having the user learn" the recommended workflow (design with brainstorming / permission organization with permissions-audit / Auto mode / spec・plan preview) so that the user themselves can continue to use it**. Each tool is not something "I (the assistant) quietly run," but rather something to teach the user, saying "in this kind of situation, it is good to use this," so that the user can choose and use it.
It is a proposal, not mandatory: What is shown here is a "recommendation."permissions-audit Both the execution of and switching to Auto mode arechosen by the user (opt-in). Respecting "not doing it this time" is also fine, and you may proceed directly to implementation.
Idempotent and low-friction: Even if called first every time from a technical skill, do not repeat it.If it is already in place, skip immediately. Skip items that are already in place in the "current state check" below, and lightly propose only the missing items.
Do not automatically change the environment from the skill: Switching to Auto mode and final application of settings areuser operations. This skill stays limited to guidance and, when the user desires it, work such as running permissions-audit.

Premise: Installation of necessary plugins (if not installed, guidance/user operation)

This workflow consists of two Claude Code pluginsUse . If not installed,propose installation(whether to do it is the user's decision), and the installation command isexecuted by the user on Claude Code(it cannot be installed from the skill).

superpowers（brainstorming / writing-plans / subagent-driven-development etc.)
- Installation: /plugin marketplace add anthropics/claude-plugins-official → /plugin install superpowers@claude-plugins-official
- (another source is possible: /plugin marketplace add obra/superpowers-marketplace → /plugin install superpowers@superpowers-marketplace）
permissions-audit（.claude/settings.json organize allow/deny)
- Installation: /plugin marketplace add https://github.com/makikub/claude-code-plugin.git → /plugin install permissions-audit@makikub-plugins
Installation check: /plugin(list) to see whether superpowers / permissions-audit are enabled. If already enabled, skip this section.
★When working in VSCode (a Visual Studio Code extension): Once the plugin installation is complete,prompt a restart of VSCode (or the extension). Right after installation, the plugin/skill may not be loaded, so guide the user as follows: "Installation is complete. If you are using VSCode, please restart VSCode (the extension) once before continuing."
※markdown-to-html is not a plugin,project skills（.claude/skills/markdown-to-html/). For projects that don't have it, discuss alternatives.

Prerequisite: Put the always-ON rules into CLAUDE.md (proposal, opt-in, and placement are the user's choice)

This skill is the authoritative source for the detailed procedures of "the order of design → planning → spec" and "Markdown preview of spec/plan"the authoritative source of the detailed proceduresIt has (the sections below). However,skills are loaded only when invokedso theseautomatic firing in all sessions (always ON)— especially the preview's "opens automatically without being told each time" — if you want this,add a short trigger rule to CLAUDE.md (auto-loaded every time)This is necessary. Also make this part of the environment setup andproposeit (opt-in, whether to do it is the user's decision, skip if it already exists).

★Have the user choose where to append(always confirm which one to put it in):

(A) Global ~/.claude/CLAUDE.md → Always ON in all projects(if you work with baserCMS5 across multiple projects, basically this one)
(B) Project CLAUDE.md(directly under the project, CLAUDE.md etc.) → Always ON only for that project(when you want it to apply only within this project)

Propose appending the following two blocks to the CLAUDE.md on the side the user chose (skip if it already exists):

> 下記2つは全プロジェクト共通の常時ONルール（要点のみ）。詳細手順は `basercms5-claude-workflow-setup` スキルに集約（あるプロジェクトはそれを正本に参照／無くても下記要点で運用可）。

## spec / plan などの Markdown プレビュー（常時ON・要点）
- spec/plan などレビュー目的の Markdown を作成・更新したら、HTML 化してブラウザで開くまで自動で行う（毎回言われなくても）。`markdown-to-html`（scripts/md_to_html.py、完全HTML文書・--fragment なし）で scratchpad へ出力 → `open` 表示（生成HTMLはコミットしない、更新時は再生成）。スキルが無いPJは代替を相談。

## brainstorming（設計）→ plan プレビュー → spec 書き出し（常時ON・要点）
- superpowers:brainstorming の設計は、いきなり docs/superpowers/specs/ に書き出さず、plan モードで plan ファイル記述 → ExitPlanMode でレビュー → 承認＆反映 → docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 書き出し → 上記プレビュー → writing-plans の順（plan モードでレビューを挟むとき）。通常対話の brainstorming は従来どおり直接 spec でよい。

※ The markdown-to-html used for preview is required as a skill in each project (if absent, prepare one or discuss an alternative).

Usage (proposal flow)

Before starting development/migration for the 5 series,propose the following in order. Each step is "check the current state → propose if not in order → execute if the user wishes".

Check the current state (confirm first): "Is it the design phase or the implementation phase?", ".claude/settings.json Are the permissions for this organized?", "Do you intend to use Auto mode?". If it's in order, skip the corresponding step.
permissions-audit Organize permissions with (opt-in): permissions-audit で .claude/settings.json organize the allow/deny forproposethis. Confirm whether to do it, and if the user wishes, execute it (deny dangerous operations, allow frequently used commands).★Tell the user: If you organize permissions, you can use Auto mode (automatic approval) with peace of mind(Dangerous operations are already denied, so even auto-approval won't run out of control.) = permissions-audit is the preparation for running Auto mode safely.
Guide the user to switch to Auto mode (user action): Once permissions are organized, suggest that switching Claude Code to Auto mode(auto-approval) and proceeding will be efficient.Auto mode cannot be enabled from a skill, so the user performs the switch. Do not recommend Auto mode before organizing (auto-approval while unorganized is dangerous).
For design, /brainstorming "communicate to the user as a recommendation" to use superpowers: This skill does not launch brainstorming on its own."When you want to do something like new development or a relatively large modification, it is recommended not to start implementing right away, but to switch to plan mode and design with the /brainstorming skill before proceeding" — communicate this to the user(suggestion). This enables the user to decide "I want to design with brainstorming" (the actual design dialogue flows as: exploration → one question at a time → 2–3 proposals → agreement per section).
- Note: brainstorming is not launched automatically; it is invoked when the user wants to proceed with it (or when they request "start from design"). If superpowers is not installed, guide them to the installation guidance in the prerequisites section.
To the implementation phase: Once the design is settled, follow the "design → plan → spec order" below, and proceed with implementation using technical skills (the authoritative source is basercms5-plugin-development / basercms5-theme-development, common rules are basercms5-development, migration is basercms-plugin-4-to-5-upgrade / basercms-plugin-5x-update) + tests basercms-unittest . For how to proceed with large-scale plugin migration (cross-cutting code check → cross-cutting syntax 5-series conversion → test & browser), refer to basercms-plugin-4-to-5-upgrade"How to proceed with migration".

Design → plan → spec order (when inserting review in plan mode)

Theauthoritative source for this procedure is this skill（~/.claude/CLAUDE.md side is already consolidated into key points + references to this skill, preventing duplication).

superpowers:brainstorming When designing withimmediately docs/superpowers/specs/ , do not write the final design to, review in the plan preview.

★Prerequisite: Reviewing in plan preview requires ExitPlanMode , and this can only be used in plan mode. Therefore, it is recommended to first switch to plan mode and then call brainstorming(this makes it easier for the user to review in plan preview). Switching to plan mode is a user action (Shift+Tab to enter plan mode). The assistant should say "Let's switch to plan mode first and design".

Switch to plan mode → Within it, proceed with the brainstorming dialogue (exploration → one question at a time → 2–3 proposals → agreement per section).
Write the agreed final design to the plan fileし、ExitPlanMode and submit it for approval (plan preview) (at this stage, docs/superpowers/specs/ export towriting-plans transition to is not done yet).
The user reviews in the plan preview and reflects feedback (revise if needed and ExitPlanMode again).
Once approved,the final design after reflecting the review to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md export to → convert to HTML and display in the preview below → superpowers:writing-plans to the implementation plan.

Summary: brainstorming dialogue → plan file → ExitPlanMode (review) → approval & reflection → docs/superpowers/specs/ export spec to → writing-plans。
Note: brainstorming in normal dialogue when not in plan mode is as before (direct spec export). This order is for "when you want to insert a review in plan mode."

Markdown preview of spec / plan

Such as spec (design document) or plan (implementation plan)When you create or update Markdown for review purposes, convert it to HTML and open it in the browserup to (automatically, without being told "preview it" every time). The output destination is a temporary directory such as scratchpad,open <output.html> display with (Do not commit generated HTML) and regenerate when Markdown is updated.

Conversion method (priority order, fall back to the next if unavailable):
1. markdown-to-html skill（scripts/md_to_html.py, self-contained with no external libraries) tocomplete HTML documentoutput (--fragment none). ← Recommended.
2. The skill isprojects without itthen (= likely to happen in other PJs), fall back to one of the following:
  - (a) As environment setup, markdown-to-html suggest preparing the skill for that project(one dependency-free Python script. opt-in).
  - (b) pandoc <in>.md -o <out>.html If is installed, convert with it → open。
  - (c) If neither is available, convert to HTML with minimal conversion (write and run a Python markdown library or a simple conversion script in scratchpad) → open。
3. If any of these are difficult, tell them so andhave the user choose(proceed without preview / prepare a conversion method).
In short, "convert to HTML and display in the browser" as long as that objective can be achieved, do not stop based on the presence or absence of a specific skill.

Auto mode assumptions and cautions

Assumptions: Before using Auto mode (auto-approval), permissions-audit organize permissions withdangerous operations already deniedand keep it that way. Auto-approval without organizing is dangerous.
Cannot be enabled from the skill: Auto mode is a Claude Code CLI feature. This skill only advises "switching here is efficient"; the user performs the switch.
If organized, iterative implementation after design agreement (cross-cutting rewrites, tests, ledger updates, etc.) runs efficiently with Auto mode.

When asking the user to verify browser behavior, specify the target URL (always ON)

If a subagent could not verify in the browser due to sandbox constraints, or if you are asking the user to visually verify after implementation is complete,always specify the URL of the page you want them to check（/recruit/採用情報/ don't just mention a path like that). Include the local development environment domain (e.g. https://<project>.localhost/...) and present it in a form that can actually be clicked/copied to access.
Present URLs as Markdown links.
Reason: if you only mention a path, the user has to reassemble the URL each time. Make the behavior verification request startable in one action, not just "what" but "where".
★Always verify connectivity of the baserCMS5 admin screen URL before handing it over (do not hand it over based on guesswork). Real examples (occurred twice in the same session): (a) inferred from another plugin's URL pattern,plugin-a/plugin_bs/indexreturned 404 (correctly, a different dash-separated form based on the target plugin's adminNavigation setting), (b) BcBlog's article edit URL was not/edit/{postId}but/edit/{blogContentId}/{postId}is the correct form (because the controller'sbeforeFilterrequires pass.0 as blogContentId), and/edit/{postId}causes a BcException saying "Content data not found".
- Verification procedure: ①docker exec <container> sh -c 'cd <v5> && bin/cake routes 2>&1 | grep -i <plugin名またはcontroller名>'check the actual route pattern (plugin/prefix/controller/action), ② while not logged in, hitcurl -sk -o /dev/null -w '%{http_code}'andif 302 (redirect to login), the route is correct, if 404 the route itself is wrong, if 500-series it is an application-side exception (sometimes detectable as far as the curl stage).
- This one extra step prevents the back-and-forth of "I thought it was a bug but it was a URL specification mistake" (just as with the "measure in production" stance of basercms-theme-4-to-5-upgrade F-23, prioritize actual measurement over guesswork).

Related skills

Design: superpowers:brainstorming / Planning: superpowers:writing-plans
Permission organization: permissions-audit
Technical patterns (implementation): basercms5-development(basis of 5-series common rules) / basercms5-plugin-development(authoritative source for plugin development) / basercms5-theme-development(authoritative source for theme development) / basercms-plugin-4-to-5-upgrade(plugin 4→5 rewrite + "how to proceed with migration") / basercms-plugin-5x-update(updates between 5.x) / basercms4-to-5-upgrade(Entire site 4→5)
Test run: basercms-unittest
Preview conversion: markdown-to-html