@unifocl/claude-plugin 0.0.0

package/commands/context.md

@@ -0,0 +1,29 @@
+Hydrate full scene context from the active unifocl project for agent reasoning.
+
+Arguments (optional — pass any combination): $ARGUMENTS
+  --project <path>   explicit project path
+  --depth <n>        hierarchy/asset traversal depth (default: 6 for hierarchy, 4 for project)
+  --limit <n>        max objects to return
+  --compact          omit null/default fields to reduce token usage
+
+Steps:
+
+1. Dump the scene hierarchy (GameObject tree):
+   `unifocl exec "/dump hierarchy --format json --depth 6 --limit 2000 $ARGUMENTS" --agentic --format json`
+
+2. Dump the project asset structure:
+   `unifocl exec "/dump project --format json --depth 4 --limit 1000 $ARGUMENTS" --agentic --format json`
+
+3. For inspector detail on a specific object — identify its path from the hierarchy dump, then:
+   `unifocl exec "/inspect <path>" --agentic --format json $ARGUMENTS`
+   followed by:
+   `unifocl exec "/dump inspector --format json $ARGUMENTS" --agentic --format json`
+
+4. Summarize findings:
+   - Active scene name (from hierarchy root metadata)
+   - Total GameObjects, root-level objects, any disabled objects
+   - Scripts and components attached to key objects
+   - Any missing script references (null component entries)
+
+Use this context before planning any `/mutate` operation so mutation paths target correct objects.
+If no project is open, run `/init` first.

package/commands/init.md

@@ -0,0 +1,24 @@
+Initialize the unifocl bridge in a Unity project.
+
+Project path (optional — defaults to current working directory if omitted): $ARGUMENTS
+
+Steps:
+
+1. Run the init command to install the editor-side bridge package:
+   `unifocl exec "/init $ARGUMENTS" --agentic --format json`
+
+2. If `ok` is false, inspect the `message` field and surface the error. Common causes:
+   - Path does not contain `ProjectSettings/ProjectVersion.txt` (not a Unity project root)
+   - Unity Editor is not installed or not detected
+   - Write permission denied on `Packages/` directory
+
+3. After a successful `/init`, confirm the bridge is ready:
+   `unifocl exec "/status" --agentic --format json --project "$ARGUMENTS"`
+   Check that `data.mode` is `bridge` (Unity Editor connected) or `host` (headless/batch).
+
+4. If `protocolMismatch` appears in the response, the editor package is outdated — re-run step 1 to redeploy the updated version.
+
+Next steps after a successful init:
+- Use `/context` to hydrate scene state before any mutations.
+- Use `/mutate` for guided scene mutations with dry-run validation.
+- For concurrent multi-agent workflows, use `src/unifocl/scripts/agent-worktree.sh setup` instead of this command.

package/commands/mutate.md

@@ -0,0 +1,40 @@
+Guided scene mutation with mandatory dry-run validation first.
+
+Describe what to mutate: $ARGUMENTS
+
+Follow this order exactly — never skip the dry-run step.
+
+Step 1 — Plan
+  Based on "$ARGUMENTS", determine the /mutate op array.
+  Call `GetMutateSchema` via the unifocl MCP server to review all supported ops and required fields.
+  Supported ops: create, rename, remove, move, toggle_active, add_component, remove_component,
+                 set_field, toggle_field, toggle_component.
+
+Step 2 — Validate (static schema check, no Unity needed)
+  Call `ValidateMutateBatch` via MCP with your planned JSON array.
+  Fix any validation errors before proceeding.
+
+Step 3 — Dry-run (preview without applying)
+  `unifocl exec "/mutate --dry-run <json-array>" --agentic --format json`
+  Inspect the `diff` in the response. Verify object paths match the scene hierarchy from `/context`.
+  Do NOT proceed if `data.allOk` is false — fix ops first.
+
+Step 4 — Execute (apply for real)
+  `unifocl exec "/mutate <json-array>" --agentic --format json`
+  Confirm `data.allOk: true` and `data.succeeded == data.total`.
+  If `--continue-on-error` was used, check `data.errors` for partial failures.
+
+Step 5 — Verify
+  Re-run `/context` (or a targeted dump) to confirm the scene reflects the expected changes.
+
+Path format rules:
+- Scene root: `/`
+- Top-level object: `/ObjectName`
+- Nested: `/Parent/Child/Grandchild`
+- Names are case-sensitive and must match exactly as shown in `/dump hierarchy`
+
+Mode availability:
+- Host mode (no Unity Editor open): create, rename, remove, move, toggle_active
+- Bridge mode (Unity Editor open with com.unifocl.cli): all ops including add_component, remove_component, set_field, toggle_field, toggle_component
+
+For multi-step workflows, pass `--session-seed <id>` across exec calls to share project context without re-specifying --project every time.

package/commands/status.md

@@ -0,0 +1,33 @@
+Check unifocl daemon and project status.
+
+Optional project path or flags: $ARGUMENTS
+
+Steps:
+
+1. Get current status:
+   `unifocl exec "/status" --agentic --format json $ARGUMENTS`
+
+2. Report from the response:
+   - `data.daemon` — running port and uptime
+   - `data.mode` — `bridge` (Unity Editor connected) or `host` (headless/batch)
+   - `data.project` — loaded project path and name
+   - `data.editor` — Unity Editor version in use
+   - `data.session` — active session seed if set
+
+3. If daemon is not running:
+   `unifocl exec "/daemon ps" --agentic --format json`
+   Lists all running daemon instances with ports, uptime, and associated projects.
+
+4. If no project is open, use `/init` to initialize the bridge, then `/context` to load scene state.
+
+5. If environment issues are suspected (missing Unity Editor path, incompatible protocol version, etc.):
+   `unifocl exec "/doctor" --agentic --format json`
+
+MCP server tools available when daemon is up:
+  - `ListCommands(scope, query, limit)` — discover all unifocl commands by scope (root/project/inspector/all)
+  - `LookupCommand(command, scope)` — exact or fuzzy command lookup with signature and description
+  - `GetMutateSchema()` — full /mutate op schema with all supported fields and types
+  - `ValidateMutateBatch(opsJson)` — pre-validate a mutation batch without executing
+  - `GetAgentWorkflowGuide()` — complete agentic workflow reference, version-matched to this binary
+  - `GetCategories()` — list custom tool categories from the project manifest
+  - `LoadCategory(name)` — register a category's [UnifoclCommand] tools as live MCP tools

package/commands/workflow.md

@@ -0,0 +1,44 @@
+Full agentic workflow guide for unifocl Unity operations.
+
+Task or workflow to plan: $ARGUMENTS
+
+Start by calling `GetAgentWorkflowGuide` via the unifocl MCP server. It returns the authoritative,
+version-matched workflow reference — always prefer it over static docs for exact flags and field names.
+
+Standard session pattern:
+
+1. Setup
+   Install: `brew install unifocl` (macOS) or run `scripts/install.ps1` (Windows).
+   Initialize bridge: `/init <project-path>` (see `/init` slash command).
+   The MCP server starts automatically when Claude Code loads this plugin.
+
+2. Open project
+   `unifocl exec "/open <project-path>" --agentic --format json`
+   Wait for `data.ok: true` before proceeding.
+
+3. Hydrate context
+   Use `/context` to dump hierarchy + project structure before any mutations.
+   Always read context before planning mutations — paths are case-sensitive.
+
+4. Discover commands
+   `ListCommands(scope="all")` via MCP for full catalog.
+   `LookupCommand(command="...")` for a specific command's signature.
+   Prefer MCP lookups over reading README — lower token cost.
+
+5. Mutate scenes
+   Always follow dry-run-first. Use `/mutate` for guided mutation.
+   For [UnifoclCommand] custom tools:
+     a. `GetCategories()` — list available tool categories from project manifest
+     b. `LoadCategory(name)` — register category tools as live MCP tools
+     c. Call the custom tool via MCP
+     d. `ReloadManifest()` after Unity recompiles new [UnifoclCommand] methods
+
+6. Multi-agent / worktrees
+   Provision isolated worktrees: `src/unifocl/scripts/agent-worktree.sh setup --worktree-path <path> --branch <name>/<task>`
+   Never share mutable worktrees across concurrent agents.
+
+7. Session efficiency
+   Pass `--session-seed <id>` to reuse project context across multiple exec calls.
+   Eliminates repeated /open overhead in multi-step workflows.
+
+Apply the above principles to accomplish: $ARGUMENTS

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@unifocl/claude-plugin",
+  "version": "0.0.0",
+  "description": "Claude Code plugin for unifocl — auto-configures MCP server and slash commands for Unity project workflows.",
+  "keywords": ["unity", "unifocl", "claude", "mcp", "claude-code-plugin"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kiankinakomochi/unifocl.git",
+    "directory": "src/unifocl.claude-plugin"
+  },
+  "files": [
+    "commands/",
+    "package.json"
+  ],
+  "claude": {
+    "mcpServers": {
+      "unifocl": {
+        "command": "unifocl",
+        "args": ["--mcp-server"]
+      }
+    },
+    "commands": "./commands"
+  }
+}