add skills

Author: AkiKurisu

Documentation~/skills/ceres/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ceres
+description: Practical handbook for extending Ceres Flow in Unity projects. Use when Codex needs to add or review Ceres Flow containers, ImplementableEvent or ExecutableEvent events, ExecutableFunction APIs, ExecutableFunctionLibrary classes, custom Flow nodes, generic nodes, port-array nodes, or diagnose Ceres source generator, ILPP, linker, or hot reload issues.
+---
+
+# Ceres
+
+Use this skill when working with Ceres Flow extension code in a Unity project.
+Prefer existing Ceres package patterns over inventing new graph infrastructure.
+
+## First Steps
+
+1. Locate the Ceres package before making decisions. Common locations:
+   - `Packages/Ceres`
+   - `Packages/com.kurisu.ceres`
+   - a Unity package listed as `com.kurisu.ceres`
+2. Read the relevant Ceres source or docs near the user's task. Useful package docs usually live in `Documentation~/docs`.
+3. Choose one path below and load only the matching reference file.
+
+## Extension Paths
+
+- **Containers and code generation**: Read `references/containers-and-codegen.md` when creating or modifying Flow containers, graph assets, runtime objects, ScriptableObject containers, or `[GenerateFlow]` classes.
+- **Events and executable functions**: Read `references/events-and-functions.md` when exposing C# APIs to Flow, adding `[ImplementableEvent]`, creating custom `[ExecutableEvent]` event types, or writing `ExecutableFunctionLibrary` classes.
+- **Custom nodes**: Read `references/custom-nodes.md` when implementing a custom node, generic node, port-array node, port metadata, or custom node behavior.
+- **Troubleshooting**: Read `references/troubleshooting.md` when generated code, ILPP event injection, function discovery, type preservation, hot reload, or Ceres editor search behavior is wrong.
+
+## Working Rules
+
+- Do not change Ceres package internals for ordinary user extension work. Add extension code in the user's Unity project unless the user explicitly asks to modify Ceres itself.
+- Keep Ceres Flow APIs in runtime assemblies and editor-only helpers in editor assemblies.
+- Prefer `FlowGraphObject`, `FlowGraphAsset`, `FlowGraphInstanceObject`, and `FlowGraphScriptableObject` before designing custom containers.
+- Prefer `[ExecutableFunction]` and `ExecutableFunctionLibrary` for exposing C# methods. Use custom nodes only when the behavior needs state, custom execution flow, async control, dynamic ports, or editor-specific node shape.
+- Do not teach or implement programmatic graph/blueprint creation from this skill unless the user explicitly asks for it; if asked, inspect the current Ceres source first because there is no single stable public GraphBuilder facade.
+- Validate with Unity compilation or the most local available compile/test signal, and inspect generated warnings when source generation or ILPP is involved.

Documentation~/skills/ceres/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ceres"
+  short_description: "Guide Ceres Flow extension work in Unity"
+  default_prompt: "Use $ceres to add a Ceres Flow extension following the package's event, function, and node patterns."

Documentation~/skills/ceres/references/containers-and-codegen.md

@@ -0,0 +1,76 @@
+# Ceres Containers And Code Generation
+
+Use this reference when adding or modifying Ceres Flow containers or generated container implementations.
+
+## Container Decision Guide
+
+- Use `FlowGraphObject` for normal scene `MonoBehaviour` gameplay logic with graph data stored on the component.
+- Use `FlowGraphAsset` when one graph asset should be reused by multiple runtime instances. Set `runtimeType` so the editor knows what `Self`, properties, and implementable events should target.
+- Use `FlowGraphInstanceObject` for a scene object that executes a referenced `FlowGraphAsset`.
+- Use `FlowGraphScriptableObject` when the logic asset should own and execute its own graph, such as skills, states, buffs, dialogue, or other asset-driven behavior.
+- Create a custom `[GenerateFlow] partial` class only when the built-in containers do not fit the runtime ownership model.
+
+## Core Interfaces
+
+- `IFlowGraphContainer` owns persistent graph data:
+  - `FlowGraph GetFlowGraph()`
+  - `FlowGraphData GetFlowGraphData()`
+  - `void SetGraphData(CeresGraphData graphData)`
+  - `UObject Object`
+- `IFlowGraphRuntime` owns the runtime graph instance:
+  - `UObject Object`
+  - `FlowGraph Graph`
+- `FlowGraphObjectBase` caches a runtime `FlowGraph`, compiles it on first `Graph` access, and disposes it through `ReleaseGraph()`.
+
+## GenerateFlow
+
+`[GenerateFlow]` tells `Ceres.SourceGenerator` to generate container/runtime boilerplate for a `partial` class.
+
+```csharp
+using Ceres.Graph.Flow.Annotations;
+using UnityEngine;
+
+[GenerateFlow(GenerateImplementation = true, GenerateRuntime = true)]
+public partial class MyFlowRuntime : MonoBehaviour
+{
+}
+```
+
+Generation flags:
+
+- `GenerateImplementation = true`: generate serialized `FlowGraphData graphData`, `Object`, `GetFlowGraph()`, `GetFlowGraphData()`, `SetGraphData()`, and protected `GetGraphData()`.
+- `GenerateRuntime = true`: generate runtime `Graph` cache, compile-on-first-access, and `ReleaseGraph()`.
+
+Built-in patterns:
+
+- `FlowGraphScriptableObjectBase`: generated container implementation only.
+- `FlowGraphScriptableObject`: generated runtime only, inheriting the container implementation from the base class.
+- `FlowGraphObject`: generated container implementation; runtime caching is handled by `FlowGraphObjectBase`.
+
+## Source Generator Constraints
+
+- The class must be `partial`.
+- The class must have a base type in the declaration for the generator receiver to pick it up.
+- Prefer normal namespace declarations. If behavior seems missing, inspect generated output and generator logs before assuming the C# code is wrong.
+- The project assembly must reference Ceres; generators skip assemblies that do not reference the Ceres assembly.
+
+## Runtime Lifecycle
+
+Use this pattern when manually compiling a runtime graph:
+
+```csharp
+using var context = FlowGraphCompilationContext.GetPooled();
+using var compiler = CeresGraphCompiler.GetPooled(graph, context);
+graph.Compile(compiler);
+```
+
+Do not mutate persistent `FlowGraphData` during play mode unless the workflow explicitly supports hot reload. In editor mode, clone graph data before creating instances when persistent data must stay untouched.
+
+## Useful Package Files
+
+- `Runtime/Flow/FlowGraphObject.cs`
+- `Runtime/Flow/FlowGraphAsset.cs`
+- `Runtime/Flow/FlowGraphInstanceObject.cs`
+- `Runtime/Flow/FlowGraphScriptableObject.cs`
+- `Runtime/Flow/Annotations/GenerateFlowAttribute.cs`
+- `Runtime/SourceGenerators/Source~/Ceres.SourceGenerator/Generators/FlowGraphGenerator.cs`

Documentation~/skills/ceres/references/custom-nodes.md

@@ -0,0 +1,219 @@
+# Ceres Custom Nodes
+
+Use this reference when writing custom Flow nodes, generic nodes, dynamic port nodes, or port behavior.
+
+## Choose A Base Class
+
+- Use `FlowNode` for simple synchronous nodes. Override `LocalExecute(ExecutionContext)`. Flow continues through the default `exec` port.
+- Use `ForwardNode` when the node is in a forward chain but needs async work or custom continuation.
+- Use `ExecutableNode` when the node needs full execution control or should run only in dependency path.
+
+Minimal synchronous node:
+
+```csharp
+using System;
+using Ceres.Annotations;
+using Ceres.Graph;
+using Ceres.Graph.Flow;
+
+[Serializable]
+[CeresGroup("Gameplay")]
+[CeresLabel("Add Score")]
+public class FlowNode_AddScore : FlowNode
+{
+    [InputPort, CeresLabel("Amount")]
+    public CeresPort<int> amount = new(1);
+
+    protected override void LocalExecute(ExecutionContext executionContext)
+    {
+        // Apply score.
+    }
+}
+```
+
+Async/custom continuation node:
+
+```csharp
+using System;
+using Ceres.Annotations;
+using Ceres.Graph;
+using Ceres.Graph.Flow;
+using Cysharp.Threading.Tasks;
+
+[Serializable]
+[CeresGroup("Utilities")]
+[CeresLabel("Delay")]
+public class FlowNode_Delay : ForwardNode
+{
+    [InputPort]
+    public CeresPort<float> seconds = new(1f);
+
+    [OutputPort(false), CeresLabel("")]
+    public NodePort exec;
+
+    protected override async UniTask Execute(ExecutionContext executionContext)
+    {
+        await UniTask.Delay(TimeSpan.FromSeconds(seconds.Value),
+            cancellationToken: executionContext.Context.GetCancellationTokenOnDestroy());
+        executionContext.SetNext(exec.GetT<ExecutableNode>());
+    }
+}
+```
+
+## Ports
+
+- Use `[InputPort] public CeresPort<T> name` for data inputs.
+- Use `[OutputPort] public CeresPort<T> name` for data outputs.
+- Use `[OutputPort(false)] public NodePort exec` for execution outputs.
+- Use `NodePort.GetT<ExecutableNode>()` to resolve the connected next node at runtime.
+- Give default values by constructing ports, such as `new CeresPort<float>(1f)`.
+- Use `[HideInGraphEditor]` for internal fields or connection-only ports.
+- Use `[CeresLabel]` to make port and node labels readable.
+- Use `[NodeInfo]` for tooltips.
+
+## Execution Path Metadata
+
+Use dependency path only for nodes that produce values without relying on forward order.
+
+```csharp
+[CeresMetadata("style = ConstNode", "path = Dependency")]
+public class FlowNode_ReadValue : ExecutableNode
+{
+}
+```
+
+Forward path is the default and should be used for side effects, control flow, async work, and Unity object mutation.
+
+## Port Arrays
+
+Use `IReadOnlyPortArrayNode` for fixed dynamic arrays and `IPortArrayNode` when the editor can resize them.
+Only one port array is supported per node type.
+
+```csharp
+using System;
+using Ceres.Annotations;
+using Ceres.Graph;
+using Ceres.Graph.Flow;
+using Cysharp.Threading.Tasks;
+using UnityEngine;
+
+[Serializable]
+[CeresGroup("Flow Control")]
+[CeresLabel("Sequence")]
+[CeresMetadata("style = ForwardNode")]
+public class FlowNode_SequenceLike : ForwardNode, ISerializationCallbackReceiver, IPortArrayNode
+{
+    [OutputPort(false), CeresLabel("Then"), CeresMetadata("DefaultLength = 2")]
+    public NodePort[] outputs;
+
+    [HideInGraphEditor]
+    public int outputCount;
+
+    protected override async UniTask Execute(ExecutionContext executionContext)
+    {
+        foreach (var output in outputs)
+        {
+            var next = output.GetT<ExecutableNode>();
+            if (next != null)
+                await executionContext.Forward(next);
+        }
+    }
+
+    public void OnBeforeSerialize() { }
+
+    public void OnAfterDeserialize()
+    {
+        outputs = new NodePort[outputCount];
+        for (var i = 0; i < outputCount; i++)
+            outputs[i] = new NodePort();
+    }
+
+    public int GetPortArrayLength() => outputCount;
+    public string GetPortArrayFieldName() => nameof(outputs);
+    public void SetPortArrayLength(int newLength) => outputCount = newLength;
+}
+```
+
+## Generic Nodes
+
+Generic nodes need two classes:
+
+- Runtime node: `FlowNode_NameT<T...>`
+- Template class: `FlowNode_NameT_Template : GenericNodeTemplate`
+
+The template name must match `{node type name without arity}_Template`.
+
+```csharp
+using System;
+using System.Linq;
+using Ceres.Annotations;
+using Ceres.Graph;
+using Ceres.Graph.Flow;
+using Ceres.Utilities;
+using Cysharp.Threading.Tasks;
+
+[Serializable]
+[CeresGroup("Utilities")]
+[CeresLabel("Cast to {0}")]
+public class FlowNode_CastLikeT<TFrom, TTo> : ForwardNode where TTo : TFrom
+{
+    [InputPort, HideInGraphEditor]
+    public CeresPort<TFrom> source;
+
+    [OutputPort]
+    public CeresPort<TTo> result;
+
+    [OutputPort(false), CeresLabel("")]
+    public NodePort exec;
+
+    protected override UniTask Execute(ExecutionContext executionContext)
+    {
+        result.Value = (TTo)source.Value;
+        executionContext.SetNext(exec.GetT<ExecutableNode>());
+        return UniTask.CompletedTask;
+    }
+}
+
+public class FlowNode_CastLikeT_Template : GenericNodeTemplate
+{
+    public override bool RequirePort() => true;
+
+    public override Type[] GetGenericArguments(Type portValueType, Type selectArgumentType)
+    {
+        return new[] { portValueType, selectArgumentType };
+    }
+
+    public override Type[] GetAvailableArguments(Type portValueType)
+    {
+        return CeresPort.GetAssignedPortValueTypes()
+            .Where(type => type.IsAssignableTo(portValueType) && type != portValueType)
+            .ToArray();
+    }
+}
+```
+
+Template guidance:
+
+- Return `true` from `RequirePort()` when type arguments depend on a dragged port.
+- Return selectable types from `GetAvailableArguments`.
+- Return generic arguments in the same order as the node type parameters.
+- Cache expensive type lists in static fields.
+
+## Metadata And Search
+
+- `[CeresGroup("Group/Subgroup")]` controls search grouping.
+- `[CeresLabel("Display")]` controls node, function, and port display text.
+- `[CeresMetadata("style = ConstNode")]` controls editor style classes.
+- `[RequirePort(typeof(SomeType))]` hides a node unless it is created from a compatible dragged port.
+- `[HideInGraphEditor]` hides serialized fields from property UI.
+
+## Useful Package Files
+
+- `Documentation~/docs/flow_custom_node.md`
+- `Documentation~/docs/flow_generic_node.md`
+- `Documentation~/docs/flow_advanced.md`
+- `Runtime/Core/Models/Graph/Nodes/CeresNode.cs`
+- `Runtime/Core/Models/Graph/Nodes/GenericNodeTemplate.cs`
+- `Runtime/Core/Models/Graph/Nodes/PortArrayNodeReflection.cs`
+- `Runtime/Core/Models/Graph/Ports/CeresPort.cs`
+- `Runtime/Flow/Models/Nodes/Core/ExecutableNode.cs`