loopforge 1.1.1 → 1.3.0

package/dist/tests/runtime.test.js

@@ -0,0 +1,323 @@
+/** LoopForge — Runtime tests (v1.2).
+ *
+ *  Tests: LoopRuntime lifecycle, run() convenience function,
+ *  heartbeat, timeout, stall, stop(), error handling.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { LoopRuntime, run } from "../runtime.js";
+import { RuntimeStatus, makeSelfEvaluation } from "../protocol.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+function makeAgentOutput(opts = {}) {
+    const se = makeSelfEvaluation({
+        success: true,
+        output_summary: "Task completed successfully.",
+        constraint_violations: [],
+        should_continue: true,
+        ...opts,
+    });
+    return [
+        "## Result",
+        "",
+        "I completed the task as requested.",
+        "",
+        "---loopforge-eval",
+        JSON.stringify(se, null, 2),
+        "---end-loopforge-eval",
+        "",
+    ].join("\n");
+}
+function makeFailingOutput(violations) {
+    return makeAgentOutput({
+        success: false,
+        output_summary: "Task partially completed.",
+        constraint_violations: violations,
+        should_continue: true,
+    });
+}
+function mockExecutor(responses) {
+    let idx = 0;
+    return async (_prompt, _ctx) => {
+        if (idx >= responses.length) {
+            throw new Error("mockExecutor: no more responses");
+        }
+        return responses[idx++];
+    };
+}
+function slowExecutor(responses, delayMs) {
+    let idx = 0;
+    return async (_prompt, _ctx) => {
+        if (idx >= responses.length) {
+            throw new Error("slowExecutor: no more responses");
+        }
+        await new Promise((r) => setTimeout(r, delayMs));
+        return responses[idx++];
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// run() convenience function
+// ═══════════════════════════════════════════════════════════════════════════
+describe("run() — convenience function", () => {
+    it("completes 3-round loop with auto-generated loopId", async () => {
+        const responses = [
+            makeAgentOutput({ should_continue: true }),
+            makeAgentOutput({ should_continue: true }),
+            makeAgentOutput({ should_continue: false }),
+        ];
+        const result = await run({
+            task: "Test task for minimal config",
+            execute: mockExecutor(responses),
+            maxRounds: 10,
+        });
+        assert.equal(result.stopReason, "task_complete");
+        assert.equal(result.success, true);
+        assert.equal(result.roundsCompleted, 3);
+        assert.equal(result.qualityTrajectory.length, 3);
+        // All rounds should have quality 5 (success + no violations)
+        for (const q of result.qualityTrajectory) {
+            assert.equal(q, 5);
+        }
+    });
+    it("stops on task_complete when should_continue=false", async () => {
+        const result = await run({
+            task: "Test task complete",
+            execute: mockExecutor([
+                makeAgentOutput({ should_continue: false }),
+            ]),
+            maxRounds: 10,
+        });
+        assert.equal(result.stopReason, "task_complete");
+        assert.equal(result.roundsCompleted, 1);
+    });
+    it("stops on max_rounds when agent always continues", async () => {
+        // Use ascending quality to avoid circuit breaker (flat 5,5,5 fires breaker)
+        const responses = [
+            makeAgentOutput({ success: false, constraint_violations: [], should_continue: true }), // quality 1
+            makeAgentOutput({ success: true, constraint_violations: [], should_continue: true }), // quality 5
+            makeAgentOutput({ success: true, constraint_violations: [], should_continue: true }), // quality 5
+        ];
+        const result = await run({
+            task: "Test max rounds",
+            execute: mockExecutor(responses),
+            maxRounds: 3,
+        });
+        assert.equal(result.stopReason, "max_rounds");
+        assert.equal(result.roundsCompleted, 3);
+    });
+    it("stops on executor_failure after consecutive errors", async () => {
+        let calls = 0;
+        const result = await run({
+            task: "Test executor failure",
+            execute: async () => {
+                calls++;
+                throw new Error("API key expired");
+            },
+            maxRounds: 10,
+            maxConsecutiveErrors: 3,
+        });
+        assert.equal(result.stopReason, "executor_failure");
+        assert.equal(calls, 3);
+    });
+    it("recovers from a single execute error", async () => {
+        let calls = 0;
+        const result = await run({
+            task: "Test recover from error",
+            execute: async () => {
+                calls++;
+                if (calls === 1)
+                    throw new Error("transient error");
+                return makeAgentOutput({ should_continue: false });
+            },
+            maxRounds: 10,
+        });
+        // Should succeed — only 1 error, not 3 consecutive
+        assert.equal(result.stopReason, "task_complete");
+        assert.equal(calls, 2);
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// LoopRuntime class
+// ═══════════════════════════════════════════════════════════════════════════
+describe("LoopRuntime", () => {
+    it("status transitions: IDLE → RUNNING → STOPPED", async () => {
+        const rt = new LoopRuntime({
+            task: "Test status transitions",
+            execute: mockExecutor([
+                makeAgentOutput({ should_continue: false }),
+            ]),
+        });
+        assert.equal(rt.status, "idle");
+        const result = await rt.start();
+        assert.equal(result.stopReason, "task_complete");
+        // After start() resolves, runtime is stopped
+        const finalStatus = rt.status;
+        assert.notEqual(finalStatus, RuntimeStatus.RUNNING);
+        assert.notEqual(finalStatus, RuntimeStatus.IDLE);
+    });
+    it("stop() mid-loop stops gracefully", async () => {
+        const rt = new LoopRuntime({
+            task: "Test stop mid-loop",
+            execute: mockExecutor([
+                makeAgentOutput({ should_continue: true }),
+                makeAgentOutput({ should_continue: true }),
+                makeAgentOutput({ should_continue: true }),
+            ]),
+            maxRounds: 10,
+            onRoundComplete: (info) => {
+                if (info.round === 2) {
+                    rt.stop();
+                }
+            },
+        });
+        const result = await rt.start();
+        assert.equal(result.stopReason, "stopped");
+        // stop() is called in round 2's onRoundComplete; the for-loop
+        // increments to round 3 before checking status, so roundsCompleted
+        // reflects the incremented counter
+        assert.ok(result.roundsCompleted <= 3);
+    });
+    it("getCurrentRound and getQualityTrajectory work", async () => {
+        const rt = new LoopRuntime({
+            task: "Test accessors",
+            execute: mockExecutor([
+                makeAgentOutput({ should_continue: true }),
+                makeAgentOutput({ should_continue: false }),
+            ]),
+            maxRounds: 10,
+        });
+        assert.equal(rt.getCurrentRound(), 1); // before start
+        assert.equal(rt.getQualityTrajectory().length, 0);
+        await rt.start();
+        assert.equal(rt.getQualityTrajectory().length, 2);
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Heartbeat & timeout
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Heartbeat & timeout", () => {
+    it("heartbeat events fire during slow execute", async () => {
+        const heartbeats = [];
+        const result = await run({
+            task: "Test heartbeat",
+            execute: slowExecutor([makeAgentOutput({ should_continue: false })], 150),
+            heartbeatIntervalMs: 50,
+            roundTimeoutMs: 5000,
+            maxRounds: 10,
+            onHeartbeat: (info) => {
+                heartbeats.push(info);
+            },
+        });
+        assert.equal(result.stopReason, "task_complete");
+        // Should have received at least one heartbeat during the 150ms delay
+        assert.ok(heartbeats.length >= 1, `expected >=1 heartbeats, got ${heartbeats.length}`);
+    });
+    it("timeout sets signal.aborted", async () => {
+        let signalWasAborted = false;
+        const result = await run({
+            task: "Test timeout",
+            execute: async (_prompt, ctx) => {
+                // Sleep past the timeout
+                await new Promise((r) => setTimeout(r, 200));
+                if (ctx && ctx.signal.aborted) {
+                    signalWasAborted = true;
+                }
+                return makeAgentOutput({ should_continue: false });
+            },
+            roundTimeoutMs: 50,
+            heartbeatIntervalMs: 25,
+            stallGraceMs: 5000,
+            maxRounds: 10,
+        });
+        assert.equal(result.stopReason, "task_complete");
+        assert.ok(signalWasAborted, "signal.aborted should be true after timeout");
+    });
+    it("interactive mode does not trigger timeout", async () => {
+        let timeoutFired = false;
+        const result = await run({
+            task: "Test interactive",
+            execute: async (_prompt, _ctx) => {
+                await new Promise((r) => setTimeout(r, 150));
+                return makeAgentOutput({ should_continue: false });
+            },
+            interactive: true,
+            roundTimeoutMs: 50,
+            heartbeatIntervalMs: 25,
+            maxRounds: 10,
+            onTimeout: () => {
+                timeoutFired = true;
+            },
+        });
+        assert.equal(result.stopReason, "task_complete");
+        assert.equal(timeoutFired, false);
+    });
+    it("reportProgress resets stall timer", async () => {
+        let reported = false;
+        const result = await run({
+            task: "Test reportProgress",
+            execute: async (_prompt, ctx) => {
+                ctx?.reportProgress("still working...");
+                reported = true;
+                await new Promise((r) => setTimeout(r, 50));
+                return makeAgentOutput({ should_continue: false });
+            },
+            roundTimeoutMs: 5000,
+            heartbeatIntervalMs: 20,
+            maxRounds: 10,
+        });
+        assert.equal(result.stopReason, "task_complete");
+        assert.ok(reported);
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Circuit breaker & extraction failure
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Circuit breaker & extraction", () => {
+    it("circuit breaker triggers after consecutive low quality", async () => {
+        // Generate failing outputs for 5+ rounds to trigger circuit breaker
+        const responses = Array.from({ length: 10 }, () => makeFailingOutput(["violated constraint X"]));
+        const result = await run({
+            task: "Test circuit breaker",
+            execute: mockExecutor(responses),
+            maxRounds: 10,
+        });
+        // Either circuit_breaker or max_rounds — depends on policy
+        assert.ok(result.stopReason === "circuit_breaker" ||
+            result.stopReason === "max_rounds", `expected circuit_breaker or max_rounds, got ${result.stopReason}`);
+    });
+    it("stops on extraction failure (no eval block)", async () => {
+        const result = await run({
+            task: "Test extraction failure",
+            execute: mockExecutor([
+                makeAgentOutput({ should_continue: true }),
+                "No structured eval block here, still need to continue working on more tasks.", // heuristic will detect "remaining" → should_continue=true, but extraction is heuristic → stalled
+            ]),
+            maxRounds: 10,
+        });
+        // Extraction via heuristic → extractionSucceeded=false → stalled
+        assert.equal(result.stopReason, "stalled");
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Stall detection
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Stall detection", () => {
+    it("stalls when execute exceeds timeout + stall grace", async () => {
+        const result = await run({
+            task: "Test stall",
+            execute: async (_prompt, _ctx) => {
+                // Sleep past timeout + stall grace
+                await new Promise((r) => setTimeout(r, 300));
+                return makeAgentOutput({ should_continue: false });
+            },
+            roundTimeoutMs: 50,
+            heartbeatIntervalMs: 25,
+            stallGraceMs: 50,
+            maxRounds: 10,
+        });
+        // Should be stalled (status was set to STALLED but execute returned)
+        assert.ok(["stalled", "task_complete"].includes(result.stopReason), `expected stalled or task_complete, got ${result.stopReason}`);
+    });
+});
+//# sourceMappingURL=runtime.test.js.map

package/dist/tests/runtime.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.test.js","sourceRoot":"","sources":["../../src/tests/runtime.test.ts"],"names":[],"mappings":"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"}

package/loop_policy.json

@@ -37,6 +37,13 @@
     "feedback_flush_interval": 5,
     "max_circuit_breaker": 3
   },
+  "runtime": {
+    "max_rounds": 20,
+    "round_timeout_ms": 600000,
+    "heartbeat_interval_ms": 30000,
+    "stall_grace_ms": 300000,
+    "max_consecutive_errors": 3
+  },
   "backend": {
     "vault_path": ".promptcraft/prompt_vault.json",
     "global_vault_path": "~/.promptcraft/global_vault.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopforge",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Loop-Time Intelligence Layer for AI coding agents — per-iteration prompt compiler with structured memory, constraint inheritance, and drift correction.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,23 +18,25 @@
       "import": "./dist/replay.js",
       "types": "./dist/replay.d.ts"
     },
-    "./autonomous": {
-      "import": "./dist/autonomous.js",
-      "types": "./dist/autonomous.d.ts"
+    "./mcp": {
+      "import": "./dist/mcp/server.js",
+      "types": "./dist/mcp/server.d.ts"
     }
   },
   "bin": {
-    "loopforge": "./dist/cli.js"
+    "loopforge": "./dist/cli.js",
+    "loopforge-mcp": "./dist/mcp-server.js"
   },
   "files": [
     "dist",
+    "skills",
     "loop_policy.json",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc && node dist/generate-schema.js",
     "generate-schema": "tsc && node dist/generate-schema.js",
-    "test": "tsc && node dist/generate-schema.js && node --test dist/tests/*.test.js",
+    "test": "tsc && node dist/generate-schema.js && node --test dist/tests/*.test.js && node -e \"require('fs').rmSync('.promptcraft',{recursive:true,force:true})\"",
     "test:watch": "tsc && node --test --watch dist/tests/*.test.js",
     "check": "tsc --noEmit"
   },

package/skills/perception/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: perception
+description: Multi-round autonomous loop driver powered by LoopForge MCP. Compiles context-aware prompts per iteration, tracks quality, inherits constraints, and stops when work is done — not when rounds run out.
+---
+
+# Perception — Loop-Time Intelligence Skill
+
+**Perception** turns any AI agent into a self-aware multi-round executor. It
+drives the LoopForge MCP server (`loopforge-mcp`) to compile per-iteration
+prompts from running quality trajectory, constraint inheritance, and drift
+detection — maintaining cognitive stability across long-horizon loops.
+
+Works with Claude Code, Codex, and any MCP-capable host. Zero configuration
+beyond having `loopforge-mcp` registered as an MCP server.
+
+## When to Activate
+
+Activate when the user says any of:
+- `/loop <task>` — start an autonomous multi-round loop
+- "do this in a loop", "keep going until done", "iterate on this"
+- Any task that clearly needs 3+ rounds (audit, refactor, migrate, review-and-fix cycles)
+
+Also activate implicitly when the user's request is too large for a single
+round (e.g. "audit the entire codebase and fix every issue").
+
+## Core Workflow
+
+```
+┌─────────────────────────────────────────────────────┐
+│  1. loopforge_start(task, constraints, maxRounds)    │
+│     → sessionId + Round 1 prompt                     │
+│                                                      │
+│  2. Execute the prompt (read, write, test, fix)      │
+│     MUST include ---loopforge-eval block in output   │
+│                                                      │
+│  3. loopforge_next(sessionId, output)                │
+│     → if prompt: go to step 2                        │
+│     → if prompt=null: loop ended, read stopReason    │
+└─────────────────────────────────────────────────────┘
+```
+
+### Step-by-step
+
+**Step 1 — Start the loop:**
+```
+Call loopforge_start with:
+  task:        required — the full task description
+  maxRounds:   optional — default 20 from policy
+  constraints: optional — hard constraints as string[]
+  domain:      optional — domain hint (solidity, react, rust…)
+
+Keep the returned sessionId — you will need it for every subsequent call.
+```
+
+**Step 2 — Execute the round:**
+Execute the compiled prompt exactly as you would any user task. Read files,
+write code, run tests, fix bugs. The prompt already contains the task scope,
+constraints, and quality expectations for this specific round.
+
+**CRITICAL: Every round's output MUST end with a self-evaluation block:**
+```
+---loopforge-eval
+{
+  "success": true,
+  "output_summary": "Fixed 3 reentrancy bugs in withdraw() and deposit(). All 12 tests pass.",
+  "constraint_violations": [],
+  "should_continue": true
+}
+---end-loopforge-eval
+```
+
+**Field rules:**
+
+| Field | Type | Rule |
+|-------|------|------|
+| `success` | boolean | `true` ONLY if all hard constraints met AND the task goal achieved |
+| `output_summary` | string | Specific, actionable. What was DONE this round — not what was attempted |
+| `constraint_violations` | string[] | Constraints the agent actually violated this round. Be honest — hiding violations corrupts the quality signal and defeats the circuit breaker |
+| `should_continue` | boolean | `false` ONLY when the ENTIRE task is complete. Partial progress = `true` |
+
+**Why this matters:** Without a valid `---loopforge-eval` block, extraction
+fails and the loop stops with `stopReason: stalled`. The circuit breaker
+uses `success` + `violations` to compute quality scores — lying here defeats
+the only mechanism that prevents infinite loops.
+
+**Step 3 — Advance to next round:**
+```
+Call loopforge_next with:
+  sessionId: from loopforge_start
+  output:    your FULL output from this round (including the eval block)
+```
+
+If the result has `prompt: null`, the loop has ended. Read `stopReason`:
+- `task_complete` — you reported should_continue=false. Work is done.
+- `circuit_breaker` — quality flat or declining for 3+ rounds. Review your approach.
+- `max_rounds` — hit the round limit. Decide whether to extend or accept.
+- `stalled` — no valid self-eval block found. Check your output format.
+
+If the result has a non-null `prompt`, execute it and repeat from Step 2.
+
+## Tool Reference
+
+| Tool | When to call | Key input | Key output |
+|------|-------------|-----------|------------|
+| `loopforge_start` | Beginning of every loop | `task`, `maxRounds?`, `constraints?` | `sessionId`, round 1 `prompt` |
+| `loopforge_next` | After executing every round | `sessionId`, `output` (with eval block) | next `prompt` or `null` + `stopReason` |
+| `loopforge_status` | Mid-loop checkpoint, user asks "how's it going" | `sessionId` | `round`, `qualityTrajectory`, `status` |
+| `loopforge_stop` | User wants to abort, fatal error | `sessionId` | `roundsCompleted`, final trajectory |
+| `loopforge_list` | User asks "what loops are running" | — | `sessions[]` |
+| `loopforge_replay` | After loop ends, user asks "show me what happened" | `sessionId` | `timeline[]` with all rounds |
+
+## Quality Signals (Read the Room)
+
+The prompt changes between rounds based on your trajectory. Pay attention to:
+
+- **Compile level** — `l0` (cached, fast path), `l1` (patched, mild drift),
+  `l2` (full recompile, significant change). L2 means the compiler detected a
+  major shift — read the prompt carefully.
+- **Warnings** — constraint violations accumulating, task drift, quality
+  decline. These are the compiler begging you to course-correct.
+- **Technique rotation** — the compiler may switch from `zero-shot-cot` to
+  `tree-of-thought` if quality drops. Follow the new technique.
+
+## Stop Condition Matrix
+
+| Condition | stopReason | What to do |
+|-----------|-----------|------------|
+| You set `should_continue: false` | `task_complete` | Report final results to user |
+| 3+ rounds of flat/declining quality | `circuit_breaker` | Tell user the approach is stuck, suggest a different strategy |
+| Round count reached `maxRounds` | `max_rounds` | Summarize progress, ask user whether to extend |
+| No `---loopforge-eval` block found | `stalled` | Fix your output format and restart |
+| User interrupts or fatal error | (call `loopforge_stop`) | Clean stop with trajectory preserved |
+
+## Rules
+
+1. **Never skip the eval block.** No exceptions. If you forget, the loop stalls.
+2. **Be honest in self-evaluation.** Lying about success or hiding violations
+   produces a false quality signal. The circuit breaker exists to stop bad
+   loops — if you fake quality=5 every round, it fires anyway.
+3. **One loop per task.** Don't reuse a sessionId across different tasks.
+4. **Execute the prompt you're given.** The compiler may change technique or
+   narrow scope between rounds. Trust it — it sees the trajectory.
+5. **Call loopforge_next within the same turn.** Don't leave a round hanging
+   across conversation turns. The MCP server is in-memory.
+
+## Example
+
+```
+User: /loop "Audit the ERC20 token in contracts/Token.sol for security issues"
+
+Agent:
+  → loopforge_start({ task: "Audit ERC20 token in contracts/Token.sol for security issues",
+                       domain: "solidity",
+                       constraints: ["must not break existing tests", "follow check-effects-interactions"] })
+  ← { sessionId: "abc-123", round: 1, prompt: "## LoopForge Loop Compile — Round 1\n...", level: "l2" }
+
+  [Executes prompt: reads Token.sol, identifies 4 issues, writes audit notes]
+
+  Output ends with:
+  ---loopforge-eval
+  {"success":false,"output_summary":"Found 4 potential issues: 2 reentrancy, 1 overflow, 1 access control. Not yet fixed.","constraint_violations":[],"should_continue":true}
+  ---end-loopforge-eval
+
+  → loopforge_next({ sessionId: "abc-123", output: <full output> })
+  ← { sessionId: "abc-123", round: 2, prompt: "## LoopForge Loop Compile — Round 2\n...", level: "l1" }
+
+  [Executes prompt: fixes 3 issues, 1 needs more investigation]
+
+  ---loopforge-eval
+  {"success":false,"output_summary":"Fixed reentrancy in withdraw() and overflow in calcReward(). Access control issue in setOwner() needs design discussion.","constraint_violations":[],"should_continue":true}
+  ---end-loopforge-eval
+
+  → loopforge_next({ sessionId: "abc-123", output: <full output> })
+  ← { sessionId: "abc-123", round: 3, prompt: "## LoopForge Loop Compile — Round 3\n...", level: "l0" }
+
+  [Executes prompt: documents access control issue for user decision, all fixes pass tests]
+
+  ---loopforge-eval
+  {"success":true,"output_summary":"All fixable issues resolved. 1 access control design question flagged for user. 24/24 tests pass.","constraint_violations":[],"should_continue":false}
+  ---end-loopforge-eval
+
+  → loopforge_next({ sessionId: "abc-123", output: <full output> })
+  ← { sessionId: "abc-123", round: 3, prompt: null, stopReason: "task_complete", quality: 5 }
+
+  Reports to user: "Audit complete in 3 rounds. 3 issues fixed, 1 design question flagged."
+```

package/skills/prompt-techniques/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: prompt-techniques
+description: >
+  Reference catalog of 7 prompt engineering techniques. This skill should be
+  used when the AI needs to recall the purpose, method steps, and use cases
+  of techniques like zero-shot, few-shot, chain-of-thought, step-back,
+  least-to-most, or tree-of-thought. It is a pure reference skill — no
+  workflow instructions, only technique documentation loaded on demand.
+---
+
+# Prompt Techniques Reference
+
+This skill catalogs seven prompt engineering techniques. Use `references/` files
+to load detailed technique documentation on demand. Each reference includes:
+purpose, input requirements, recommended JSON input templates, method steps,
+design rules, when-to-use guidance, and example use cases.
+
+## Technique Overview
+
+| Technique | Cognitive Load | Independence | When to Use |
+|-----------|---------------|-------------|-------------|
+| zero-shot | Low | Either | Simple code explanation, formatting, renaming. |
+| few-shot | Medium | Continuous | Standard CRUD modules, unit tests with fixed patterns. |
+| chain-of-thought | Medium-High | Either | Multi-step reasoning; use `zero-shot-cot` without examples, `few-shot-cot` with examples. |
+| step-back | High | Independent | Vague errors, messy legacy refactoring — abstract principles first. |
+| least-to-most | High | Continuous | Large multi-step modules — decompose into ordered sub-tasks. |
+| tree-of-thought | High | Independent | Core algorithms, crypto/signature verification, Assembly ops — explore multiple candidate paths. |
+
+## How to Use
+
+1. Read `references/<technique>.md` for the selected technique. Each reference contains:
+   - **Purpose** — what problem the technique solves.
+   - **Input Requirements** — required and optional parameters.
+   - **Recommended JSON Input** — a complete input template with example values.
+   - **Method Steps** — step-by-step construction guide.
+   - **Design Rules** — specific rules for high-quality prompt construction.
+   - **Case Generation Rules** — how to generate examples, decompositions, branches, or abstractions (where applicable).
+   - **Single-Pass vs Two-Stage** — when to use each execution mode (step-back, least-to-most).
+   - **Search Strategy Selection** — beam/dfs/expert-panel guidance (tree-of-thought).
+   - **Prompt Output Template** — a complete 8-section output skeleton with section-level format specifications. Defines the exact structure the generated prompt must follow. The technique-specific section (section 5) format varies per technique: Few-Shot uses input→output pairs, Few-Shot-CoT uses reasoning triples, Step-Back uses abstraction framework boxes, Least-to-Most uses ordered subproblems, Tree-of-Thought uses state tables + evaluation criteria. Zero-Shot omits section 5 entirely for a lightweight 7-section prompt.
+   - **When to Use** — concrete scenarios and example use cases.
+2. `references/chain-of-thought.md` covers both `zero-shot-cot` and `few-shot-cot`, including paper citations for Few-Shot-CoT.
+3. Do not load all references at once — read only the one selected by the router in Step 1.
+
+## Reference Files
+
+- `references/zero-shot.md`
+- `references/few-shot.md`
+- `references/chain-of-thought.md` (covers zero-shot-cot and few-shot-cot)
+- `references/step-back.md`
+- `references/least-to-most.md`
+- `references/tree-of-thought.md`