minimal-vibe-coding-kit 0.5.0 → 0.5.2

package/.agents/skills/sequential-thinking/references/output-schema.md

@@ -1,483 +1,124 @@
-# Sequential Thinking - Output Schema Reference
+# Sequential Thinking Output Contract
 
-Complete JSON response structure documentation.
+Return public reasoning summaries, never private chain-of-thought. Markdown is the default; JSON is opt-in.
 
-## Base Response Structure
+## Markdown Shape
 
-```typescript
-{
-  thoughtNumber: number;           // Current position (1-100)
-  totalThoughts: number;           // Estimated total (auto-adjusts)
-  nextThoughtNeeded: boolean;      // Continue flag
-  branches: string[];              // Active branch IDs
-  thoughtHistoryLength: number;    // Total processed
-  sessionContext: {                // Session metadata
-    sessionId: string;
-    remainingThoughts: number;
-    [key: string]: any;
-  }
-}
-```
-
----
-
-## Field Descriptions
-
-### `thoughtNumber` (number)
-**Current position in thought sequence**
-
-**Range:** 1-100
-**Behavior:** Increments by 1 for each thought
-**Auto-adjustment:** If exceeds `totalThoughts`, adjusts it upward
-
-**Examples:**
-```json
-{"thoughtNumber": 1}   // First thought
-{"thoughtNumber": 15}  // Fifteenth thought
-{"thoughtNumber": 100} // Maximum (limit reached)
-```
-
----
-
-### `totalThoughts` (number)
-**Estimated total thoughts needed for complete analysis**
-
-**Range:** 1-100 (matches `thoughtNumber`)
-**Behavior:** Can increase dynamically, never decreases
-**Auto-adjustment:** Matches `thoughtNumber` if exceeded
-
-**Examples:**
-```json
-// Initial estimate
-{"totalThoughts": 5}
-
-// After auto-adjustment
-{"thoughtNumber": 7, "totalThoughts": 7}
-
-// After needsMoreThoughts
-{"totalThoughts": 8}  // Was 5, added 3
-```
-
----
-
-### `nextThoughtNeeded` (boolean)
-**Whether another thought step is needed**
-
-**Values:** `true` (continue) or `false` (complete)
-**Purpose:** Flow control for reasoning loop
-**Decision:** Set by LLM based on problem completeness
-
-**Examples:**
-```json
-// Continuing analysis
-{"nextThoughtNeeded": true}
-
-// Analysis complete
-{"nextThoughtNeeded": false}
-```
-
----
-
-### `branches` (string[])
-**Array of active branch IDs**
-
-**Type:** Array of strings
-**Content:** Unique branch identifiers created during exploration
-**Deduplication:** Automatic (no duplicates)
-
-**Examples:**
-```json
-// No branches
-{"branches": []}
-
-// Single branch
-{"branches": ["alternative-approach"]}
-
-// Multiple branches
-{"branches": ["approach-a", "approach-b", "fallback"]}
-```
-
----
-
-### `thoughtHistoryLength` (number)
-**Total number of thoughts processed in session**
-
-**Type:** Integer ≥ 1
-**Behavior:** Increments by 1 with each thought
-**Includes:** Regular thoughts + revisions + branch thoughts
-
-**Examples:**
-```json
-// First thought
-{"thoughtHistoryLength": 1}
-
-// After 8 thoughts
-{"thoughtHistoryLength": 8}
-
-// With branches and revisions
-{"thoughtHistoryLength": 15}  // Main:8, Branches:5, Revisions:2
-```
+~~~markdown
+## Reasoning Summary
 
----
+Current focus: <decision>
+Marker: <marker or none>
+Evidence:
+- <observed fact>
+Uncertainty:
+- <unknown and resolution method>
+Decision: <conclusion>
+Next action: <concrete action>
+Validation: <command or check>
+~~~
 
-### `sessionContext` (object)
-**Session metadata and statistics**
+Omit empty sections instead of filling them with invented content.
 
-**Required fields:**
-- `sessionId`: Session identifier (default: "conversation")
-- `remainingThoughts`: 100 - totalThoughts
+## JSON Shape
 
-**Optional fields:**
-- `recentThoughts`: Preview of last 3 thoughts
-- `revisionsMade`: Count of revisions
-- `revisedThoughts`: Array of thought numbers revised
-- `branchDepth`: Deepest branch depth
-- Any custom metadata
+Use this shape only when the user asks for JSON:
 
-**Example:**
-```json
+~~~json
 {
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 92,
-    "recentThoughts": [
-      {"number": 8, "preview": "Synthesizing findings..."},
-      {"number": 7, "preview": "Branch B shows promise..."},
-      {"number": 6, "preview": "Analyzing Branch A..."}
-    ],
-    "revisionsMade": 1,
-    "revisedThoughts": [2]
-  }
-}
-```
-
----
-
-## Response Examples
-
-### Example 1: First Thought
-```json
-{
-  "thoughtNumber": 1,
-  "totalThoughts": 3,
-  "nextThoughtNeeded": true,
-  "branches": [],
-  "thoughtHistoryLength": 1,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 99
-  }
-}
-```
-
----
-
-### Example 2: Mid-Sequence
-```json
-{
-  "thoughtNumber": 5,
-  "totalThoughts": 8,
-  "nextThoughtNeeded": true,
-  "branches": [],
-  "thoughtHistoryLength": 5,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 95,
-    "recentThoughts": [
-      {"number": 5, "preview": "Current thought..."},
-      {"number": 4, "preview": "Previous thought..."},
-      {"number": 3, "preview": "Earlier thought..."}
-    ]
-  }
-}
-```
-
----
-
-### Example 3: With Revision
-```json
-{
-  "thoughtNumber": 6,
-  "totalThoughts": 8,
+  "thoughtNumber": 3,
+  "totalThoughts": 5,
   "nextThoughtNeeded": true,
+  "marker": "VERIFICATION",
+  "summary": "All declared skill mirrors have identical content hashes.",
+  "evidence": [
+    "Canonical and four surface hashes match."
+  ],
+  "uncertainties": [
+    "Package inclusion has not been checked yet."
+  ],
   "branches": [],
-  "thoughtHistoryLength": 6,
-  "revisionOf": 3,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 94,
-    "revisionsMade": 1,
-    "revisedThoughts": [3]
-  }
-}
-```
-
----
-
-### Example 4: With Branches
-```json
-{
-  "thoughtNumber": 7,
-  "totalThoughts": 10,
-  "nextThoughtNeeded": true,
-  "branches": ["caching", "optimization", "scaling"],
-  "thoughtHistoryLength": 12,
-  "branchInfo": {
-    "currentBranch": "optimization",
-    "fromThought": 4,
-    "branchDepth": 2
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 90
-  }
-}
-```
-
----
-
-### Example 5: Auto-Adjusted
-```json
-{
-  "thoughtNumber": 8,
-  "totalThoughts": 8,
+  "nextAction": "Run the package dry-run and inspect the file list."
+}
+~~~
+
+Allowed marker values are:
+
+~~~json
+[
+  null,
+  "REVISION",
+  "BRANCH",
+  "HYPOTHESIS",
+  "VERIFICATION",
+  "CONVERGENCE",
+  "META",
+  "FINAL"
+]
+~~~
+
+## Field Rules
+
+| Field | Type | Rule |
+| --- | --- | --- |
+| thoughtNumber | integer | positive and no greater than totalThoughts |
+| totalThoughts | integer | positive estimate; may expand or contract |
+| nextThoughtNeeded | boolean | false only at a genuine stop |
+| marker | string or null | one value from the allowlist |
+| summary | string | concise public conclusion, not hidden reasoning |
+| evidence | string array | observed facts only |
+| uncertainties | string array | owned unknowns and resolution methods |
+| branches | string array | currently open branch IDs |
+| nextAction | string | edit, check, or question |
+
+## Revision Example
+
+~~~json
+{
+  "thoughtNumber": 4,
+  "totalThoughts": 6,
   "nextThoughtNeeded": true,
+  "marker": "REVISION",
+  "summary": "The package manifest, not mirror drift, explains the missing skill.",
+  "evidence": [
+    "Mirror hashes match.",
+    "The package files list omits the skill directory."
+  ],
+  "uncertainties": [],
   "branches": [],
-  "thoughtHistoryLength": 8,
-  "totalThoughtsAdjusted": true,
-  "originalEstimate": 5,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 92
-  }
+  "nextAction": "Patch the package list and rerun the dry-run."
 }
-```
+~~~
 
----
+## Final Example
 
-### Example 6: Final Thought
-```json
+~~~json
 {
-  "thoughtNumber": 10,
-  "totalThoughts": 10,
+  "thoughtNumber": 5,
+  "totalThoughts": 5,
   "nextThoughtNeeded": false,
-  "branches": ["explored-a", "explored-b"],
-  "thoughtHistoryLength": 15,
-  "status": "complete",
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 90,
-    "branchesExplored": 2,
-    "revisionsM ade": 2
-  }
-}
-```
-
----
-
-## Error Response Structure
-
-```json
-{
-  "error": "Thought number must be between 1 and 100",
-  "thoughtNumber": 101,
-  "success": false,
-  "errorType": "validation",
-  "suggestions": [
-    "Use thought number between 1-100",
-    "Consider summarizing earlier thoughts"
+  "marker": "FINAL",
+  "summary": "The manifest repair is validated and ready for review.",
+  "evidence": [
+    "Targeted package assertion passes.",
+    "Full kit validation passes with zero failures."
   ],
-  "sessionContext": {
-    "sessionId": "conversation"
-  }
-}
-```
-
-### Error Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `error` | string | Error message |
-| `success` | boolean | Always false for errors |
-| `errorType` | string | Category: validation, runtime, configuration |
-| `suggestions` | string[] | Recovery suggestions |
-| `sessionContext` | object | Session info (even on error) |
-
----
-
-## Enhanced Response Features (Skill-Specific)
-
-### Include Thought Content
-
-Unlike MCP (metadata-only), skill responses include full thought:
-
-```json
-{
-  "thoughtNumber": 5,
-  "thoughtContent": "Analyzing the authentication flow reveals three key components...",
-  "totalThoughts": 8,
-  "nextThoughtNeeded": true,
+  "uncertainties": [],
   "branches": [],
-  "thoughtHistoryLength": 5,
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 95
-  }
-}
-```
-
----
-
-### Recent Thoughts Preview
-
-```json
-{
-  "sessionContext": {
-    "recentThoughts": [
-      {
-        "number": 5,
-        "content": "Full content of thought 5...",
-        "type": "regular",
-        "timestamp": "2026-04-05T10:30:00Z"
-      },
-      {
-        "number": 4,
-        "content": "Full content of thought 4...",
-        "type": "branch",
-        "branchId": "alt-a"
-      },
-      {
-        "number": 3,
-        "content": "Full content of thought 3...",
-        "type": "revision",
-        "revisedThought": 1
-      }
-    ]
-  }
-}
-```
-
----
-
-### Branch Summary
-
-```json
-{
-  "branches": ["approach-a", "approach-b"],
-  "branchSummary": {
-    "approach-a": {
-      "fromThought": 3,
-      "thoughtCount": 4,
-      "lastThought": 7
-    },
-    "approach-b": {
-      "fromThought": 3,
-      "thoughtCount": 2,
-      "lastThought": 5
-    }
-  }
-}
-```
-
----
-
-## Status Fields
-
-### `status` (string, optional)
-
-Added when thought sequence reaches specific states:
-
-```json
-// Approaching limit
-{"status": "approaching_limit"}  // thoughtNumber > 90
-
-// Limit reached
-{"status": "limit_reached"}      // thoughtNumber = 100
-
-// Analysis complete
-{"status": "complete"}           // nextThoughtNeeded = false
-
-// Error state
-{"status": "failed"}             // Error occurred
-```
-
----
-
-## Metadata Tracking
-
-### Adjustment Tracking
-```json
-{
-  "totalThoughtsAdjusted": true,
-  "originalEstimate": 5,
-  "currentEstimate": 8,
-  "adjustmentsMade": 1
-}
-```
-
-### Revision Tracking
-```json
-{
-  "revisionOf": 3,
-  "sessionContext": {
-    "revisionsMade": 2,
-    "revisedThoughts": [2, 3]
-  }
+  "nextAction": "Review the diff."
 }
-```
+~~~
 
-### Branch Tracking
-```json
-{
-  "branches": ["a", "b"],
-  "sessionContext": {
-    "totalBranches": 2,
-    "activeBranches": 2,
-    "branchDepth": 3
-  }
-}
-```
-
----
-
-## Comparison: MCP vs Skill Output
-
-### MCP Server Output (Metadata Only)
-```json
-{
-  "thoughtNumber": 5,
-  "totalThoughts": 8,
-  "nextThoughtNeeded": true,
-  "branches": ["alt-a"],
-  "thoughtHistoryLength": 12
-}
-```
-
-### Skill Output (Enhanced)
-```json
-{
-  "thoughtNumber": 5,
-  "thoughtContent": "Full thought text here...",
-  "totalThoughts": 8,
-  "nextThoughtNeeded": true,
-  "branches": ["alt-a"],
-  "thoughtHistoryLength": 12,
-  "branchInfo": {
-    "currentBranch": "alt-a",
-    "fromThought": 3
-  },
-  "sessionContext": {
-    "sessionId": "conversation",
-    "remainingThoughts": 95,
-    "recentThoughts": [...]
-  }
-}
-```
+## Invalid Output
 
-**Enhancement:** Skill includes full context for transparency.
+Reject or repair output that:
 
----
+- contains private-thought fields or invented pseudo-session metadata;
+- claims persistent state or automatic runtime processing;
+- uses an undeclared marker;
+- calls a hypothesis verified without observed evidence;
+- includes secrets, personal data, or raw sensitive logs;
+- leaves open branches when marker is FINAL;
+- places thoughtNumber above totalThoughts.
 
-**For usage patterns, see:** [patterns.md](patterns.md)  
-**For examples, see:** [../examples/](../examples/)  
-**For parameters, see:** [parameters.md](parameters.md)
+The skill should explain malformed user-supplied hints in plain language rather than inventing a processor error object.