diff --git a/docs/knowledge/ontology-agents.md b/docs/knowledge/ontology-agents.md new file mode 100644 index 000000000..341c22c52 --- /dev/null +++ b/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. diff --git a/docs/knowledge/ontology-toplevel.md b/docs/knowledge/ontology-toplevel.md new file mode 100644 index 000000000..2218bd618 --- /dev/null +++ b/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). diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 2fd19ba1e..36014d00d 100644 --- a/skills/brainstorming/SKILL.md +++ b/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:** diff --git a/skills/brainstorming/references/agents-analysis-framework.md b/skills/brainstorming/references/agents-analysis-framework.md new file mode 100644 index 000000000..aa9d1ea52 --- /dev/null +++ b/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. diff --git a/skills/brainstorming/references/toplevel-analysis-framework.md b/skills/brainstorming/references/toplevel-analysis-framework.md new file mode 100644 index 000000000..805cc5570 --- /dev/null +++ b/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". diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index ca77290c8..abc4a222f 100644 --- a/skills/executing-plans/SKILL.md +++ b/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. diff --git a/skills/executing-plans/references/agents-analysis-framework.md b/skills/executing-plans/references/agents-analysis-framework.md new file mode 100644 index 000000000..aa9d1ea52 --- /dev/null +++ b/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. diff --git a/skills/executing-plans/references/toplevel-analysis-framework.md b/skills/executing-plans/references/toplevel-analysis-framework.md new file mode 100644 index 000000000..805cc5570 --- /dev/null +++ b/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". diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md index f0e33952c..6a8631c36 100644 --- a/skills/requesting-code-review/SKILL.md +++ b/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:** diff --git a/skills/requesting-code-review/references/agents-analysis-framework.md b/skills/requesting-code-review/references/agents-analysis-framework.md new file mode 100644 index 000000000..aa9d1ea52 --- /dev/null +++ b/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. diff --git a/skills/requesting-code-review/references/toplevel-analysis-framework.md b/skills/requesting-code-review/references/toplevel-analysis-framework.md new file mode 100644 index 000000000..805cc5570 --- /dev/null +++ b/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". diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 448ca3193..4b5ecaf55 100644 --- a/skills/writing-plans/SKILL.md +++ b/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: diff --git a/skills/writing-plans/references/agents-analysis-framework.md b/skills/writing-plans/references/agents-analysis-framework.md new file mode 100644 index 000000000..aa9d1ea52 --- /dev/null +++ b/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. diff --git a/skills/writing-plans/references/toplevel-analysis-framework.md b/skills/writing-plans/references/toplevel-analysis-framework.md new file mode 100644 index 000000000..805cc5570 --- /dev/null +++ b/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".