@quybt93/pcgf 0.0.1

package/.agents/skills/bmad-walkthrough/step-03-detail-pass.md

@@ -0,0 +1,106 @@
+# Step 3: Detail Pass
+
+Display: `Orientation → Walkthrough → [Detail Pass] → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- The detail pass surfaces what the human should **think about**, not what the code got wrong. Machine hardening already handled correctness. This activates risk awareness.
+- The LLM detects risk category by pattern. The human judges significance. Do not assign severity scores or numeric rankings — ordering by blast radius (below) is sequencing for readability, not a severity judgment.
+- If no high-risk spots exist, say so explicitly. Do not invent findings.
+
+## IDENTIFY RISK SPOTS
+
+Scan the diff for changes touching risk-sensitive patterns. Look for 2–5 spots where a mistake would have the highest blast radius — not the most complex code, but the code where being wrong costs the most.
+
+Risk categories to detect:
+
+- `[auth]` — authentication, authorization, session, token, permission, access control
+- `[public API]` — new/changed endpoints, exports, public methods, interface contracts
+- `[schema]` — database migrations, schema changes, data model modifications, serialization
+- `[billing]` — payment, pricing, subscription, metering, usage tracking
+- `[infra]` — deployment, CI/CD, environment variables, config files, infrastructure
+- `[security]` — input validation, sanitization, crypto, secrets, CORS, CSP
+- `[config]` — feature flags, environment-dependent behavior, defaults
+- `[other]` — anything risk-sensitive that doesn't fit the above (e.g., concurrency, data privacy, backwards compatibility). Use a descriptive tag.
+
+Sequence spots so the highest blast radius comes first (how much breaks if this is wrong), not by diff order or file order. If more than 5 spots qualify, show the top 5 and note: "N additional spots omitted — ask if you want the full list."
+
+If the change has no spots matching these patterns, state: "No high-risk spots found in this change — the diff speaks for itself." Do not force findings.
+
+## SURFACE MACHINE HARDENING FINDINGS
+
+Check whether the spec has a `## Spec Change Log` section with entries (populated by adversarial review loops).
+
+- **If entries exist:** Read them. Surface findings that are instructive for the human reviewer — not bugs that were already fixed, but decisions the review loop flagged that the human should be aware of. Format: brief summary of what was flagged and what was decided.
+- **If no entries or no spec:** Skip this section entirely. Do not mention it.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → [Detail Pass] → Testing
+```
+
+### Risk Spots
+
+For each spot, one line:
+
+```
+- `path:line` — [tag] reason-phrase
+```
+
+Example:
+
+```
+- `src/auth/middleware.ts:42` — [auth] New token validation bypasses rate limiter
+- `migrations/003_add_index.sql:7` — [schema] Index on high-write table, check lock behavior
+- `api/routes/billing.ts:118` — [billing] Metering calculation changed, verify idempotency
+```
+
+### Machine Hardening (only if findings exist)
+
+```
+### Machine Hardening
+
+- Finding summary — what was flagged, what was decided
+- ...
+```
+
+### Closing menu
+
+End the message with:
+
+```
+---
+
+You've seen the design and the risk landscape. From here:
+- **"dig into [area]"** — I'll deep-dive that specific area with correctness focus
+- **"next"** — I'll suggest how to observe the behavior
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## TARGETED RE-REVIEW
+
+When the human says "dig into [area]" (e.g., "dig into the auth changes", "dig into the schema migration"):
+
+1. If the specified area does not map to any code in the diff, say so: "I don't see [area] in this change — did you mean something else?" Return to the closing menu.
+2. Identify all code locations in the diff relevant to the specified area.
+3. Read each location in full context (not just the diff hunk — read surrounding code).
+4. Shift to **correctness mode**: trace edge cases, check boundary conditions, verify error handling, look for off-by-one errors, race conditions, resource leaks.
+5. Present findings as a compact list — each finding is `path:line` + what you found + why it matters.
+6. If nothing concerning is found, say so: "Looked closely at [area] — nothing concerning. The implementation is solid."
+7. After presenting, show only the closing menu (not the full risk spots list again).
+
+The human can trigger multiple targeted re-reviews. Each time, present new findings and the closing menu only.
+
+## NEXT
+
+Read fully and follow `./step-04-testing.md`

package/.agents/skills/bmad-walkthrough/step-04-testing.md

@@ -0,0 +1,74 @@
+# Step 4: Testing
+
+Display: `Orientation → Walkthrough → Detail Pass → [Testing]`
+
+## Follow Global Step Rules in SKILL.md
+
+- This is **experiential**, not analytical. The detail pass asked "did you think about X?" — this says "you could see X with your own eyes."
+- Do not prescribe. The human decides whether observing the behavior is worth their time. Frame suggestions as options, not obligations.
+- Do not duplicate CI, test suites, or automated checks. Assume those exist and work. This is about manual observation — the kind of confidence-building no automated test provides.
+- If the change has no user-visible behavior, say so explicitly. Do not invent observations.
+
+## IDENTIFY OBSERVABLE BEHAVIOR
+
+Scan the diff and spec for changes that produce behavior a human could directly observe. Categories to look for:
+
+- **UI changes** — new screens, modified layouts, changed interactions, error states
+- **CLI/terminal output** — new commands, changed output, new flags or options
+- **API responses** — new endpoints, changed payloads, different status codes
+- **State changes** — database records, file system artifacts, config effects
+- **Error paths** — bad input, missing dependencies, edge conditions
+
+For each observable behavior, determine:
+
+1. **What to do** — the specific action (command to run, button to click, request to send)
+2. **What to expect** — the observable result that confirms the change works
+3. **Why bother** — one phrase connecting this observation to the change's intent (omit if obvious from context)
+
+Target 2–5 suggestions for a typical change. If more than 5 qualify, prioritize by how much confidence the observation provides relative to effort. A change with zero observable behavior is fine — do not pad with trivial observations.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → Detail Pass → [Testing]
+```
+
+Then the testing suggestions using this format:
+
+```
+### How to See It Working
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+```
+
+Include code blocks for commands or requests where helpful.
+
+If the change has no observable behavior, replace the suggestions with:
+
+```
+### How to See It Working
+
+This change is internal — no user-visible behavior to observe. The diff and tests tell the full story.
+```
+
+### Closing
+
+End the message with:
+
+```
+---
+
+You've seen the change and how to verify it. When you're ready to make a call, just say so.
+```
+
+## NEXT
+
+When the human signals they're ready to make a decision about this {change_type}, read fully and follow `./step-05-wrapup.md`

package/.agents/skills/bmad-walkthrough/step-05-wrapup.md

@@ -0,0 +1,30 @@
+# Step 5: Wrap-Up
+
+Display: `Orientation → Walkthrough → Detail Pass → Testing → [Wrap-Up]`
+
+## Follow Global Step Rules in SKILL.md
+
+## PROMPT FOR DECISION
+
+```
+---
+
+Review complete. What's the call on this {change_type}?
+- **Approve** — ship it (I can help with interactive patching first if needed)
+- **Rework** — back to the drawing board (revert, revise the spec, try a different approach)
+- **Discuss** — something's still on your mind
+```
+
+HALT — do not proceed until the user makes their choice.
+
+## ACT ON DECISION
+
+- **Approve**: Acknowledge briefly. If the human wants to patch something before shipping, help apply the fix interactively. If reviewing a PR, offer to approve via `gh pr review --approve` — but confirm with the human before executing, since this is a visible action on a shared resource.
+- **Rework**: Ask what went wrong — was it the approach, the spec, or the implementation? Help the human decide on next steps (revert commit, open an issue, revise the spec, etc.). Help draft specific, actionable feedback tied to `path:line` locations if the change is a PR from someone else.
+- **Discuss**: Open conversation — answer questions, explore concerns, dig into any aspect. After discussion, return to the decision prompt above.
+
+## On Complete
+
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete`
+
+If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/README.md

@@ -0,0 +1,111 @@
+# Phaser Casual Game Factory (`pcgf`)
+
+Plugin + installer kiểu BMAD cho game casual Phaser.
+
+## Dùng giống BMAD
+
+Vào thư mục project game:
+
+```bash
+npx @quybt93/pcgf install --yes
+```
+
+Tên npm là **`@quybt93/pcgf`** (unscoped `pcgf` bị registry từ chối vì gần `pg`/`pkg`/…). Binary CLI vẫn là lệnh `pcgf`.
+
+Installs into the current directory with defaults `cursor,codex` + scaffold.
+
+Nếu thiếu `phaser`/`rxjs`, sẽ hỏi xác nhận rồi tự `npm install`.
+Dùng `--yes` để bỏ hỏi và cài deps luôn.
+
+```bash
+npx @quybt93/pcgf install --yes
+npx @quybt93/pcgf install --no-install-deps
+```
+
+### Cài lần đầu vs cập nhật skill
+
+| Lệnh | Khi nào |
+|------|---------|
+| `npx @quybt93/pcgf install --yes` | Project game **mới**. Default **có scaffold** (`src/factory/`, Boot/Home/Game stubs). |
+| `npx @quybt93/pcgf install --yes --no-scaffold` | Game **đã cài**. Chỉ refresh `_pcgf/` + `.cursor/skills/`. **Không** ghi đè `src/`. |
+| `npx @quybt93/pcgf clean --yes` rồi `install --yes --scaffold` | Dọn hết `_pcgf` + hook Cursor/Codex rồi cài lại chuẩn. |
+
+`pcgf clean --yes --with-scaffold` xóa thêm `src/factory/`. `--scaffold` trên `install` ép copy lại foundation (có thể ghi đè file factory). `--no-scaffold` khi agent chỉ cần skill/templates mới.
+
+Agent trên máy khác: game đã có `_pcgf/` thì luôn dùng `--no-scaffold` trừ khi user xin scaffold lại / `pcgf clean`.
+
+**Cách C — từ Git private (không cần publish npm):**
+
+Máy khác (cần SSH GitLab Skylink). Trong thư mục **game**:
+
+```bash
+# Lần đầu
+npx --yes --package=git+ssh://git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git pcgf install --yes
+
+# Đã cài — chỉ cập nhật skill
+npx --yes --package=git+ssh://git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git pcgf install --yes --no-scaffold
+```
+
+`npx @quybt93/pcgf` chạy sau khi đã publish npm; hoặc `npm link` local.
+
+### Để `npx @quybt93/pcgf` chạy được từ mọi máy
+
+**Cách A — publish npm:**
+
+```bash
+cd <repo-factory>
+npm publish --access public
+```
+
+Sau đó mọi project chỉ cần `npx @quybt93/pcgf install`.
+
+**Cách B — link local trên máy bạn** (chưa publish / dev):
+
+```bash
+cd /Users/quydev/orca/workspaces/plugin-casual-game-factory/main-2
+npm link
+```
+
+Rồi ở bất kỳ project nào:
+
+```bash
+pcgf install
+# hoặc
+npx @quybt93/pcgf install
+```
+
+Cách C (Git) ở trên.
+
+## Installer tạo gì
+
+| Path | Nội dung |
+|------|----------|
+| `_pcgf/` | Plugin copy + `manifest.json` (như `_bmad/`) |
+| `.cursor/skills/` | Skills Cursor (`--tools cursor`) |
+| `.agents/plugins/marketplace.json` | Marketplace Codex (`--tools codex`) |
+| `src/factory/...` | Foundation nếu `--scaffold` |
+
+## Lệnh hữu ích
+
+```bash
+npx @quybt93/pcgf install --help
+npx @quybt93/pcgf skills
+npx @quybt93/pcgf clean --yes
+npx @quybt93/pcgf clean --yes --with-scaffold
+npx @quybt93/pcgf install --list-tools
+npx @quybt93/pcgf install --yes --tools cursor
+npx @quybt93/pcgf install --yes --no-scaffold
+```
+
+## Plugin contents
+
+Chi tiết: [`plugins/phaser-casual-game-factory/README.md`](plugins/phaser-casual-game-factory/README.md)
+
+Push / Merge Request: skill `pcgf-git-merge-request` — nhánh phụ, rebase `main`, MR GitLab; không push thẳng `main`.
+
+## Codex marketplace (repo factory)
+
+```bash
+codex plugin marketplace add .
+codex plugin add phaser-casual-game-factory
+```

package/bin/pcgf.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from '../installer/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`pcgf: ${message}`);
+  process.exitCode = 1;
+});

package/installer/clean.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listSkillNames, pathExists, readJson } from './fs-utils.js';
+import { INSTALL_DIR_NAME, installRoot, manifestPath, pluginRoot } from './paths.js';
+
+function removePath(targetPath) {
+  if (!pathExists(targetPath)) {
+    return false;
+  }
+  fs.rmSync(targetPath, { recursive: true, force: true });
+  return true;
+}
+
+function readManifest(projectDir) {
+  return readJson(manifestPath(projectDir), null);
+}
+
+function collectFactorySkillNames(projectDir) {
+  const names = new Set();
+  const manifest = readManifest(projectDir);
+  for (const name of manifest?.skills ?? []) {
+    names.add(name);
+  }
+
+  const installedSkills = path.join(installRoot(projectDir), 'plugin', 'skills');
+  for (const name of listSkillNames(installedSkills)) {
+    names.add(name);
+  }
+
+  for (const name of listSkillNames(path.join(pluginRoot, 'skills'))) {
+    names.add(name);
+  }
+
+  return [...names].sort();
+}
+
+function cleanCursorSkills(projectDir, skillNames) {
+  const skillsDir = path.join(projectDir, '.cursor', 'skills');
+  if (!pathExists(skillsDir)) {
+    return [];
+  }
+
+  const removed = [];
+  for (const name of skillNames) {
+    const skillPath = path.join(skillsDir, name);
+    if (removePath(skillPath)) {
+      removed.push(path.join('.cursor', 'skills', name).replaceAll('\\', '/'));
+    }
+  }
+
+  // Drop empty .cursor/skills (and .cursor if empty) without touching other Cursor config.
+  try {
+    if (pathExists(skillsDir) && fs.readdirSync(skillsDir).length === 0) {
+      fs.rmdirSync(skillsDir);
+      const cursorDir = path.join(projectDir, '.cursor');
+      if (pathExists(cursorDir) && fs.readdirSync(cursorDir).length === 0) {
+        fs.rmdirSync(cursorDir);
+      }
+    }
+  } catch {
+    // Leave dirs if not empty / not writable.
+  }
+
+  return removed;
+}
+
+function cleanCodexMarketplace(projectDir) {
+  const marketplaceFile = path.join(projectDir, '.agents', 'plugins', 'marketplace.json');
+  if (!pathExists(marketplaceFile)) {
+    return [];
+  }
+
+  const marketplace = readJson(marketplaceFile, null);
+  const plugins = Array.isArray(marketplace?.plugins) ? marketplace.plugins : [];
+  const ours = (plugin) => plugin?.name === 'phaser-casual-game-factory';
+  const remaining = plugins.filter((plugin) => !ours(plugin));
+  const hadOurs = remaining.length !== plugins.length
+    || marketplace?.name === 'phaser-casual-game-factory-local';
+
+  if (!hadOurs && plugins.length > 0) {
+    return [];
+  }
+
+  if (remaining.length === 0 || marketplace?.name === 'phaser-casual-game-factory-local') {
+    removePath(marketplaceFile);
+    const pluginsDir = path.join(projectDir, '.agents', 'plugins');
+    try {
+      if (pathExists(pluginsDir) && fs.readdirSync(pluginsDir).length === 0) {
+        fs.rmdirSync(pluginsDir);
+      }
+      const agentsDir = path.join(projectDir, '.agents');
+      if (pathExists(agentsDir) && fs.readdirSync(agentsDir).length === 0) {
+        fs.rmdirSync(agentsDir);
+      }
+    } catch {
+      // leave parent dirs
+    }
+    return ['.agents/plugins/marketplace.json'];
+  }
+
+  marketplace.plugins = remaining;
+  fs.writeFileSync(marketplaceFile, `${JSON.stringify(marketplace, null, 2)}\n`, 'utf8');
+  return ['.agents/plugins/marketplace.json (removed pcgf entry)'];
+}
+
+/**
+ * Remove PCGF install artifacts so the project can be installed from scratch.
+ * Does not touch phaser/rxjs or game source unless withScaffold is true.
+ */
+export function runClean(options) {
+  const projectDir = path.resolve(options.directory);
+  const withScaffold = Boolean(options.withScaffold);
+  const removed = [];
+  const skillNames = collectFactorySkillNames(projectDir);
+
+  const installDir = installRoot(projectDir);
+  if (removePath(installDir)) {
+    removed.push(`${INSTALL_DIR_NAME}/`);
+  }
+
+  removed.push(...cleanCursorSkills(projectDir, skillNames));
+  removed.push(...cleanCodexMarketplace(projectDir));
+
+  if (withScaffold) {
+    const factoryDir = path.join(projectDir, 'src', 'factory');
+    if (removePath(factoryDir)) {
+      removed.push('src/factory/');
+    }
+  }
+
+  return {
+    projectDir,
+    withScaffold,
+    removed,
+    foundAnything: removed.length > 0,
+  };
+}