docs: add ontology analysis references for skills

docs/knowledge/ontology-agents.md

@@ -0,0 +1,44 @@
+# Ontology Agents (Sowa) - Superpowers Knowledge Doc
+
+Source: [Agents Ontology](https://www.jfsowa.com/ontology/agents.htm)
+Scope: Adapted for Superpowers content design. Workflow remains unchanged.
+
+## zh-CN
+
+### 核心提炼
+- 代理（agent）是“能有目的地行动的有生命实体”，但其定义依赖 *animate / capable / doing / purpose* 等基础词。
+- 基本概念存在循环性，只能通过相互关系的公理或规律来隐式刻画。
+- 亚里士多德六层心灵功能：营养、感知、欲望、运动、表象、思考，可用于代理能力分层。
+- Brooks 机器人能力等级从避障到预期，体现从反射到推理与规划的递进。
+- 人工心灵类比：软件/机器人代理可映射到资源获取、感知、偏好、行动、表象处理、推理规划。
+
+### Superpowers 适配（内容设计）
+- Brainstorming: 用“目的-能力-行动-环境”框定代理，明确可感知信息与可行动范围。
+- Write-plan: 按能力层级分配任务，避免让低层系统承担规划或预期能力。
+- Execute-plan/TDD: 用“目的-结果-失败条件”定义可验收行为，避免抽象宣称。
+- Review: 检查文案是否混淆“能力”与“意图”，是否过度承诺智能水平。
+
+### 内容设计提示（不改流程）
+- 行为叙述分层：反射 -> 感知/表征 -> 推理/规划 -> 预期他者。
+- 用户可见说明先交代“意图与限制”，再说明“动作与策略”。
+- 需要定义代理时，用关系性描述而非闭合定义。
+
+## en
+
+### Core takeaways
+- An agent is an animate entity that acts on purpose, but the definition depends on basic terms like animate, capable, doing, and purpose.
+- Primitive concepts are circular and should be captured implicitly by relational constraints, not closed-form definitions.
+- Aristotle's six functions of psyche (nutrition, perception, desire, locomotion, imagery, thought) provide a capability ladder.
+- Brooks' robot competence levels show progression from reflex to reasoning and planning.
+- For artificial agents, those functions map to resource acquisition, perception, preference, action, representation, and planning.
+
+### Superpowers fit (content design)
+- Brainstorming: frame the agent with purpose, capability, action, and environment; define what it can sense and do.
+- Write-plan: assign tasks by capability level; do not assume planning in reactive systems.
+- Execute-plan/TDD: express success and failure in terms of purpose and outcomes.
+- Review: check for confusion between capability and intent, or inflated intelligence claims.
+
+### Content design tips (no workflow changes)
+- Layer behaviors: reflex -> perception/representation -> reasoning/planning -> anticipation of others.
+- For user-facing copy, lead with intent and constraints, then describe actions.
+- When defining an agent, use relational phrasing instead of closed-form definitions.

docs/knowledge/ontology-toplevel.md

@@ -0,0 +1,48 @@
+# Ontology Top-Level Categories (Sowa) - Superpowers Knowledge Doc
+
+Source: [Toplevel Ontology](https://www.jfsowa.com/ontology/toplevel.htm)
+Scope: Adapted for Superpowers content design. Workflow remains unchanged.
+
+## zh-CN
+
+### 核心提炼
+- KR 本体顶层类别来自 Peirce 与 Whitehead，使用“格/矩阵”表达组合结构。
+- 原始范畴：Independent, Relative, Mediating, Physical, Abstract, Continuant, Occurrent，加上 `T`（实体）与 `^`（荒谬）。
+- 12 个中心类别矩阵：
+  - Object / Process / Schema / Script
+  - Juncture / Participation / Description / History
+  - Structure / Situation / Reason / Purpose
+- 类别可由原始范畴合取定义，但原始范畴只能通过公理关系隐式刻画。
+
+### Superpowers 适配（内容设计）
+- Brainstorming: 先判断需求处于“实体/关系/中介”，再判断“物理/抽象”“持续/发生”。
+- Write-plan: 用矩阵映射需求点，确保对象、过程、描述、目的都被覆盖。
+- Execute-plan/TDD: 针对 Process/Script/History 区分“发生过程”和“执行脚本”的验证点。
+- Review: 检查是否把 Reason/Purpose 写成 Description，或把 Script 当成 Process。
+
+### 内容设计提示（不改流程）
+- 叙述结构优先：实体 -> 过程 -> 描述 -> 目的。
+- 描述性内容（Description/History）与意图性内容（Reason/Purpose）分离表达。
+- 对抽象结构（Schema/Script）与实体结构（Object/Structure）分别说明。
+
+## en
+
+### Core takeaways
+- The KR top level combines Peirce and Whitehead into a lattice/matrix of categories.
+- Primitive categories: Independent, Relative, Mediating, Physical, Abstract, Continuant, Occurrent, plus `T` and `^`.
+- The 12 central categories matrix:
+  - Object / Process / Schema / Script
+  - Juncture / Participation / Description / History
+  - Structure / Situation / Reason / Purpose
+- Derived categories are conjunctions of primitives; primitives are constrained by axioms, not closed definitions.
+
+### Superpowers fit (content design)
+- Brainstorming: classify the domain as entity/relationship/mediator, then physical/abstract and continuant/occurrent.
+- Write-plan: map requirements to the matrix to cover object, process, description, and purpose.
+- Execute-plan/TDD: verify process vs script vs history distinctly.
+- Review: ensure reasons/purposes are not written as descriptions, and scripts are not treated as processes.
+
+### Content design tips (no workflow changes)
+- Organize narratives as entity -> process -> description -> purpose.
+- Separate descriptive content (description/history) from intentional content (reason/purpose).
+- Explain abstract structures (schema/script) separately from physical structures (object/structure).

skills/brainstorming/SKILL.md

@@ -32,6 +32,11 @@ Start by understanding the current project context, then ask questions one at a
 - Cover: architecture, components, data flow, error handling, testing
 - Be ready to go back and clarify if something doesn't make sense
 
+## References (Optional)
+
+- `references/agents-analysis-framework.md` - Checklist for defining agent boundaries and capabilities.
+- `references/toplevel-analysis-framework.md` - Classification tools to distinguish objects, processes, and intentions.
+
 ## After the Design
 
 **Documentation:**

skills/brainstorming/references/agents-analysis-framework.md

@@ -0,0 +1,18 @@
+# Agents Analysis Framework
+
+Use this framework to define the scope, boundaries, and capabilities of an agent or autonomous system.
+
+## Core Dimensions
+Define these for every agent:
+- **Purpose**: The specific goal or outcome the agent is responsible for.
+- **Capability**: Explicit in-scope functions and out-of-scope limitations.
+- **Perception**: What the agent can "see" (APIs, events, user input).
+- **Action**: What the agent can "do" (outputs, API calls, side effects).
+- **Environment**: Constraints, policies, and available tools.
+
+## Capability Ladder
+Assess the required intelligence level:
+1. **Reflex**: Simple trigger-response (if X then Y).
+2. **Representation**: Maintains internal state or models of the world.
+3. **Reasoning/Planning**: Evaluates multiple paths to achieve a goal.
+4. **Anticipation**: Predicts external changes or other agents' behaviors.

skills/brainstorming/references/toplevel-analysis-framework.md

@@ -0,0 +1,19 @@
+# Top-Level Analysis Framework (Sowa)
+
+Use this framework to identify missing dimensions in your domain analysis.
+
+## Classification Axes
+Checks to classify any entity:
+1. **Independent vs Relative vs Mediating**: Does it exist alone, in relation to others, or as a connection?
+2. **Physical vs Abstract**: Is it matter/energy or information?
+3. **Continuant vs Occurrent**: Does it persist in time (object) or happen over time (process)?
+
+## Coverage Matrix
+Ensure your analysis covers these central categories where applicable:
+- **Entities**: Object, Schema, Structure.
+- **Dynamic**: Process, Script, Situation.
+- **Relational**: Participation, Description, Reason, Purpose, History.
+
+## Usage
+- **Classify**: Apply the axes to your key terms to disambiguate them.
+- **Gap Check**: Use the matrix to see if you missed a "History" (record), a "Script" (plan), or a "Purpose".

skills/executing-plans/SKILL.md

@@ -74,3 +74,8 @@ After all tasks complete and verified:
 - Reference skills when plan says to
 - Between batches: just report and wait
 - Stop when blocked, don't guess
+
+## References (Optional)
+
+- `references/agents-analysis-framework.md` - Criteria for verifying agent behaviors.
+- `references/toplevel-analysis-framework.md` - Checks for preventing domain logic gaps.

skills/executing-plans/references/agents-analysis-framework.md

@@ -0,0 +1,18 @@
+# Agents Analysis Framework
+
+Use this framework to define the scope, boundaries, and capabilities of an agent or autonomous system.
+
+## Core Dimensions
+Define these for every agent:
+- **Purpose**: The specific goal or outcome the agent is responsible for.
+- **Capability**: Explicit in-scope functions and out-of-scope limitations.
+- **Perception**: What the agent can "see" (APIs, events, user input).
+- **Action**: What the agent can "do" (outputs, API calls, side effects).
+- **Environment**: Constraints, policies, and available tools.
+
+## Capability Ladder
+Assess the required intelligence level:
+1. **Reflex**: Simple trigger-response (if X then Y).
+2. **Representation**: Maintains internal state or models of the world.
+3. **Reasoning/Planning**: Evaluates multiple paths to achieve a goal.
+4. **Anticipation**: Predicts external changes or other agents' behaviors.

skills/executing-plans/references/toplevel-analysis-framework.md

@@ -0,0 +1,19 @@
+# Top-Level Analysis Framework (Sowa)
+
+Use this framework to identify missing dimensions in your domain analysis.
+
+## Classification Axes
+Checks to classify any entity:
+1. **Independent vs Relative vs Mediating**: Does it exist alone, in relation to others, or as a connection?
+2. **Physical vs Abstract**: Is it matter/energy or information?
+3. **Continuant vs Occurrent**: Does it persist in time (object) or happen over time (process)?
+
+## Coverage Matrix
+Ensure your analysis covers these central categories where applicable:
+- **Entities**: Object, Schema, Structure.
+- **Dynamic**: Process, Script, Situation.
+- **Relational**: Participation, Description, Reason, Purpose, History.
+
+## Usage
+- **Classify**: Apply the axes to your key terms to disambiguate them.
+- **Gap Check**: Use the matrix to see if you missed a "History" (record), a "Script" (plan), or a "Purpose".

skills/requesting-code-review/SKILL.md

@@ -89,6 +89,11 @@ You: [Fix progress indicators]
 - Review before merge
 - Review when stuck
 
+## References (Optional)
+
+- `references/agents-analysis-framework.md` - Checklist for reviewing agent capability claims.
+- `references/toplevel-analysis-framework.md` - Guide for reviewing domain modeling accuracy.
+
 ## Red Flags
 
 **Never:**

skills/requesting-code-review/references/agents-analysis-framework.md

@@ -0,0 +1,18 @@
+# Agents Analysis Framework
+
+Use this framework to define the scope, boundaries, and capabilities of an agent or autonomous system.
+
+## Core Dimensions
+Define these for every agent:
+- **Purpose**: The specific goal or outcome the agent is responsible for.
+- **Capability**: Explicit in-scope functions and out-of-scope limitations.
+- **Perception**: What the agent can "see" (APIs, events, user input).
+- **Action**: What the agent can "do" (outputs, API calls, side effects).
+- **Environment**: Constraints, policies, and available tools.
+
+## Capability Ladder
+Assess the required intelligence level:
+1. **Reflex**: Simple trigger-response (if X then Y).
+2. **Representation**: Maintains internal state or models of the world.
+3. **Reasoning/Planning**: Evaluates multiple paths to achieve a goal.
+4. **Anticipation**: Predicts external changes or other agents' behaviors.

skills/requesting-code-review/references/toplevel-analysis-framework.md

@@ -0,0 +1,19 @@
+# Top-Level Analysis Framework (Sowa)
+
+Use this framework to identify missing dimensions in your domain analysis.
+
+## Classification Axes
+Checks to classify any entity:
+1. **Independent vs Relative vs Mediating**: Does it exist alone, in relation to others, or as a connection?
+2. **Physical vs Abstract**: Is it matter/energy or information?
+3. **Continuant vs Occurrent**: Does it persist in time (object) or happen over time (process)?
+
+## Coverage Matrix
+Ensure your analysis covers these central categories where applicable:
+- **Entities**: Object, Schema, Structure.
+- **Dynamic**: Process, Script, Situation.
+- **Relational**: Participation, Description, Reason, Purpose, History.
+
+## Usage
+- **Classify**: Apply the axes to your key terms to disambiguate them.
+- **Gap Check**: Use the matrix to see if you missed a "History" (record), a "Script" (plan), or a "Purpose".

skills/writing-plans/SKILL.md

@@ -94,6 +94,11 @@ git commit -m "feat: add specific feature"
 - Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
 
+## References (Optional)
+
+- `references/agents-analysis-framework.md` - Guide for specifying agent scope and logic.
+- `references/toplevel-analysis-framework.md` - Framework for defining complex domain models.
+
 ## Execution Handoff
 
 After saving the plan, offer execution choice:

skills/writing-plans/references/agents-analysis-framework.md

@@ -0,0 +1,18 @@
+# Agents Analysis Framework
+
+Use this framework to define the scope, boundaries, and capabilities of an agent or autonomous system.
+
+## Core Dimensions
+Define these for every agent:
+- **Purpose**: The specific goal or outcome the agent is responsible for.
+- **Capability**: Explicit in-scope functions and out-of-scope limitations.
+- **Perception**: What the agent can "see" (APIs, events, user input).
+- **Action**: What the agent can "do" (outputs, API calls, side effects).
+- **Environment**: Constraints, policies, and available tools.
+
+## Capability Ladder
+Assess the required intelligence level:
+1. **Reflex**: Simple trigger-response (if X then Y).
+2. **Representation**: Maintains internal state or models of the world.
+3. **Reasoning/Planning**: Evaluates multiple paths to achieve a goal.
+4. **Anticipation**: Predicts external changes or other agents' behaviors.

skills/writing-plans/references/toplevel-analysis-framework.md

@@ -0,0 +1,19 @@
+# Top-Level Analysis Framework (Sowa)
+
+Use this framework to identify missing dimensions in your domain analysis.
+
+## Classification Axes
+Checks to classify any entity:
+1. **Independent vs Relative vs Mediating**: Does it exist alone, in relation to others, or as a connection?
+2. **Physical vs Abstract**: Is it matter/energy or information?
+3. **Continuant vs Occurrent**: Does it persist in time (object) or happen over time (process)?
+
+## Coverage Matrix
+Ensure your analysis covers these central categories where applicable:
+- **Entities**: Object, Schema, Structure.
+- **Dynamic**: Process, Script, Situation.
+- **Relational**: Participation, Description, Reason, Purpose, History.
+
+## Usage
+- **Classify**: Apply the axes to your key terms to disambiguate them.
+- **Gap Check**: Use the matrix to see if you missed a "History" (record), a "Script" (plan), or a "Purpose".