Skip to content

Commit 436db29

Browse files
novatechflownovatechflow
authored
Agent thought process (KafClaw#37)
* feat(cascade): add gated task lifecycle and transition persistence * feat(configure): add per-agent cascade enablement and guidance * docs: split CoT guide and reorganize docs navigation * docs: snippets * test: align shell fuzz oracle with guard regex * feat(cascade): add retry-threshold escalation policy * docs: document cascade escalation behavior
1 parent 1132b97 commit 436db29

31 files changed

Lines changed: 1797 additions & 21 deletions

‎docs/agent-concepts/CoT.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
parent: Memory Management
3+
title: CoT Cascading Protocol
4+
nav_order: 2
5+
---
6+
7+
# CoT Cascading Protocol
8+
9+
The Cascading Protocol applies Chain-of-Thought style task decomposition with strict stage gates between subtasks.
10+
11+
- Every subtask declares `required_input`, `produced_output`, and `validation_rules`.
12+
- `Task N+1` is blocked until `Task N` is committed with validated outputs.
13+
- Failures route back with deterministic reasons (`missing_input`, `missing_output`, `invalid_rules`) and retry controls.
14+
- State transitions are durable and idempotent.
15+
16+
## State Machine Infographic
17+
18+
<style>
19+
.cot-wrap {
20+
margin: 14px 0 6px;
21+
color: #18263d;
22+
font-family: "Avenir Next", "Segoe UI", "Helvetica Neue", sans-serif;
23+
}
24+
.cot-grid {
25+
display: grid;
26+
grid-template-columns: repeat(12, minmax(0, 1fr));
27+
gap: 12px;
28+
margin-top: 14px;
29+
}
30+
.cot-card {
31+
grid-column: span 12;
32+
border: 1px solid #d4deef;
33+
border-radius: 12px;
34+
background: #ffffff;
35+
padding: 12px;
36+
box-shadow: 0 6px 18px rgba(24, 45, 84, 0.07);
37+
}
38+
.cot-card svg {
39+
display: block;
40+
width: 100%;
41+
height: auto;
42+
}
43+
</style>
44+
45+
<div class="cot-wrap">
46+
<section class="cot-grid">
47+
<article class="cot-card">
48+
<svg viewBox="0 0 1120 320" role="img" aria-label="Cascading protocol state machine">
49+
<defs>
50+
<marker id="cot-arrow" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
51+
<polygon points="0,0 10,4 0,8" fill="#24509c"></polygon>
52+
</marker>
53+
<marker id="cot-arrow-fail" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
54+
<polygon points="0,0 10,4 0,8" fill="#b11f2f"></polygon>
55+
</marker>
56+
</defs>
57+
58+
<rect x="30" y="44" width="140" height="58" rx="10" fill="#eef4ff" stroke="#9bb5e6"></rect>
59+
<text x="100" y="78" text-anchor="middle" font-size="14" font-weight="700" fill="#1a4288">pending</text>
60+
61+
<rect x="200" y="44" width="140" height="58" rx="10" fill="#eef4ff" stroke="#9bb5e6"></rect>
62+
<text x="270" y="78" text-anchor="middle" font-size="14" font-weight="700" fill="#1a4288">running</text>
63+
64+
<rect x="370" y="44" width="140" height="58" rx="10" fill="#eef4ff" stroke="#9bb5e6"></rect>
65+
<text x="440" y="78" text-anchor="middle" font-size="14" font-weight="700" fill="#1a4288">self_test</text>
66+
67+
<rect x="540" y="44" width="140" height="58" rx="10" fill="#eef4ff" stroke="#9bb5e6"></rect>
68+
<text x="610" y="78" text-anchor="middle" font-size="14" font-weight="700" fill="#1a4288">validated</text>
69+
70+
<rect x="710" y="44" width="140" height="58" rx="10" fill="#eaf8f3" stroke="#9ad8c4"></rect>
71+
<text x="780" y="78" text-anchor="middle" font-size="14" font-weight="700" fill="#17634d">committed</text>
72+
73+
<rect x="880" y="44" width="170" height="58" rx="10" fill="#eaf8f3" stroke="#9ad8c4"></rect>
74+
<text x="965" y="78" text-anchor="middle" font-size="14" font-weight="700" fill="#17634d">released_next</text>
75+
76+
<rect x="760" y="212" width="150" height="58" rx="10" fill="#ffeef0" stroke="#de9aa1"></rect>
77+
<text x="835" y="246" text-anchor="middle" font-size="14" font-weight="700" fill="#8e1f2a">failed</text>
78+
79+
<rect x="930" y="212" width="170" height="58" rx="10" fill="#fff8ea" stroke="#e3c995"></rect>
80+
<text x="1015" y="238" text-anchor="middle" font-size="14" font-weight="700" fill="#84511b">Task N+1</text>
81+
<text x="1015" y="256" text-anchor="middle" font-size="11" fill="#8f6933">can start</text>
82+
83+
<line x1="170" y1="73" x2="198" y2="73" stroke="#24509c" stroke-width="2.4" marker-end="url(#cot-arrow)"></line>
84+
<line x1="340" y1="73" x2="368" y2="73" stroke="#24509c" stroke-width="2.4" marker-end="url(#cot-arrow)"></line>
85+
<line x1="510" y1="73" x2="538" y2="73" stroke="#24509c" stroke-width="2.4" marker-end="url(#cot-arrow)"></line>
86+
<line x1="680" y1="73" x2="708" y2="73" stroke="#24509c" stroke-width="2.4" marker-end="url(#cot-arrow)"></line>
87+
<line x1="850" y1="73" x2="878" y2="73" stroke="#24509c" stroke-width="2.4" marker-end="url(#cot-arrow)"></line>
88+
89+
<path d="M 440 104 C 440 150, 100 150, 100 104" fill="none" stroke="#996221" stroke-width="2.2" marker-end="url(#cot-arrow)"></path>
90+
<text x="230" y="165" text-anchor="middle" font-size="11" fill="#8f6933">validation failed + retries left</text>
91+
92+
<line x1="100" y1="104" x2="760" y2="212" stroke="#b11f2f" stroke-width="2" marker-end="url(#cot-arrow-fail)"></line>
93+
<text x="318" y="186" text-anchor="middle" font-size="11" fill="#8e1f2a">retry budget exhausted</text>
94+
95+
<line x1="270" y1="104" x2="790" y2="212" stroke="#b11f2f" stroke-width="2" marker-end="url(#cot-arrow-fail)"></line>
96+
<text x="468" y="205" text-anchor="middle" font-size="11" fill="#8e1f2a">runtime error</text>
97+
98+
<line x1="610" y1="104" x2="820" y2="212" stroke="#b11f2f" stroke-width="2" marker-end="url(#cot-arrow-fail)"></line>
99+
<text x="672" y="186" text-anchor="middle" font-size="11" fill="#8e1f2a">commit error</text>
100+
101+
<line x1="800" y1="104" x2="985" y2="212" stroke="#996221" stroke-width="2" stroke-dasharray="6,5" marker-end="url(#cot-arrow)"></line>
102+
<text x="905" y="164" text-anchor="middle" font-size="11" fill="#8f6933">unlock Task N+1</text>
103+
</svg>
104+
</article>
105+
</section>
106+
</div>
107+
108+
## When To Use
109+
110+
Use this mode for deterministic, verifiable work where output shape and validation are clear.
111+
112+
- Runbooks and operations workflows
113+
- Config generation and structured updates
114+
- Code mod pipelines and migration steps
115+
- Multi-stage tasks where each step has hard contracts
116+
117+
## When Not To Use
118+
119+
Avoid this mode for open-ended and high-ambiguity work.
120+
121+
- Creative generation and brainstorming
122+
- Exploratory research without stable validation criteria
123+
- Low-latency conversational tasks
124+
- Tasks where strict sequencing blocks useful parallelism
125+
126+
## Implications and Tradeoffs
127+
128+
- Improves reliability by preventing context drift between subtasks.
129+
- Reduces copy-of-copy distortion via explicit output validation.
130+
- Adds latency and compute cost due to retries and gate checks.
131+
- Can stall throughput if contracts are underspecified.
132+
- Requires better task design (`required_input`, `produced_output`, and validation rules must be explicit).
133+
- On retry-threshold exceed, failed transitions now trigger deterministic escalation hints for fallback model and tooling.
134+
135+
## Configuration Guidance
136+
137+
This should be enabled per agent only when the agent's workload is deterministic and auditable.
138+
139+
- Recommended: ops/runbook/config/code-mod agents
140+
- Not recommended: general-purpose chat or exploratory analysis agents
141+
142+
Use `kafclaw configure` to enable or disable cascade behavior at the agent level, and keep default behavior unchanged for agents that do not need gated execution.
143+
144+
## Migration Guide for Existing Agent Configs
145+
146+
Use this flow when upgrading an existing installation that already has `agents.list` entries.
147+
148+
1. Inspect your current agents:
149+
150+
```bash
151+
kafclaw config get agents.list
152+
```
153+
154+
2. Enable cascade only for deterministic agents:
155+
156+
```bash
157+
kafclaw configure --agent-id ops --agent-cascade-enabled-set --agent-cascade-enabled=true
158+
kafclaw configure --agent-id runbook --agent-cascade-enabled-set --agent-cascade-enabled=true
159+
```
160+
161+
3. Keep exploratory or chat agents disabled:
162+
163+
```bash
164+
kafclaw configure --agent-id main --agent-cascade-enabled-set --agent-cascade-enabled=false
165+
```
166+
167+
4. Verify persisted config:
168+
169+
```bash
170+
kafclaw config get agents.list
171+
```
172+
173+
5. Validate runtime behavior on a trace:
174+
175+
```bash
176+
kafclaw task status --trace <trace-id> --json
177+
```
178+
179+
For failure triage, see the runbook snippet in [Memory Governance Operations](/memory-management/memory-governance-operations/#cascade-failure-triage-snippet).

‎docs/agent-concepts/how-agents-work.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
parent: Agent Concepts
33
title: How Agents Work
4+
nav_order: 1
45
---
56

67
# How Agents Work

‎docs/agent-concepts/index.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
---
22
title: Agent Concepts
3-
parent: Memory Management
4-
nav_order: 1
3+
nav_order: 5
54
has_children: true
65
---
76

8-
Core concepts behind KafClaw agents, including identity, runtime behavior, tool boundaries, and memory.
7+
Core runtime concepts behind KafClaw agents, including identity, lifecycle, tool boundaries, and execution behavior.
8+
9+
## Core Pages
10+
11+
- [How Agents Work](/agent-concepts/how-agents-work/)
12+
- [Soul and Identity Files](/agent-concepts/soul-identity-tools/)
13+
- [Runtime Tools and Capabilities](/agent-concepts/runtime-tools/)

‎docs/agent-concepts/memory-notes.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
parent: Memory Management
33
title: Memory Architecture and Notes
4-
nav_order: 2
4+
nav_order: 1
55
---
66

77
# Memory Architecture and Notes
@@ -180,6 +180,10 @@ Private memory lanes, restart durability, model-switch behavior, and distributed
180180
Model switch rule: if a previously used embedding model changes, memory vectors are wiped before reindex. Adding the first embedding model later does not wipe existing text records.
181181
</div>
182182

183+
## Cascading Protocol (Gated Subtasks)
184+
185+
Full protocol details, state machine infographic, and operational guidance are documented in [CoT Cascading Protocol](/agent-concepts/CoT/).
186+
183187
## Kafka Knowledge Pool: How It Works
184188

185189
The shared knowledge pool is the distributed memory layer used when multiple claws collaborate.

‎docs/agent-concepts/runtime-tools.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
parent: Agent Concepts
33
title: Runtime Tools and Capabilities
4+
nav_order: 3
45
---
56

67
# Runtime Tools and Capabilities

‎docs/agent-concepts/soul-identity-tools.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
parent: Agent Concepts
33
title: Soul and Identity Files
4+
nav_order: 2
45
---
56

67
# Soul and Identity Files

‎docs/architecture-security/architecture-timeline.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
parent: Memory Management
2+
parent: Architecture and Security
33
title: "Architecture: Timeline and Memory"
4-
nav_order: 3
4+
nav_order: 4
55
---
66

77
# Architecture: Timeline and Memory

‎docs/architecture-security/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Architecture and Security
3-
nav_order: 7
3+
nav_order: 9
44
has_children: true
55
---
66

‎docs/collaboration/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Communication and Channels
3-
nav_order: 5
3+
nav_order: 6
44
has_children: true
55
---
66

‎docs/index.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,18 @@ KafClaw is a Go-based agent runtime with three practical deployment modes:
3434
- [WhatsApp Onboarding](./integrations/whatsapp-onboarding/)
3535
- [WhatsApp Setup](./integrations/whatsapp-setup/)
3636

37+
## Agent Concepts
38+
39+
- [Agent Concepts](./agent-concepts/)
40+
- [How Agents Work](./agent-concepts/how-agents-work/)
41+
- [Soul and Identity Files](./agent-concepts/soul-identity-tools/)
42+
- [Runtime Tools and Capabilities](./agent-concepts/runtime-tools/)
43+
3744
## Memory Management
3845

3946
- [Memory Management](./memory-management/)
4047
- [Memory Architecture and Notes](./agent-concepts/memory-notes/)
41-
- [Timeline and Memory Architecture](./architecture-security/architecture-timeline/)
42-
- [Knowledge Contracts](./reference/knowledge-contracts/)
48+
- [CoT Cascading Protocol](./agent-concepts/CoT/)
4349
- [Memory Governance Operations](./memory-management/memory-governance-operations/)
4450

4551
## Communication and Channels
@@ -76,3 +82,4 @@ KafClaw is a Go-based agent runtime with three practical deployment modes:
7682
- [CLI Reference](./reference/cli-reference/)
7783
- [API Endpoints](./reference/api-endpoints/)
7884
- [Configuration Keys](./reference/config-keys/)
85+
- [Knowledge Contracts](./reference/knowledge-contracts/)

0 commit comments

Comments
 (0)