@oleksandr.rudnychenko/sync_loop 0.3.7 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +79 -161
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,29 +1,29 @@
1
1
  # SyncLoop
2
2
 
3
- **Give your AI coding agent a structured reasoning loop.**
3
+ **Stop your AI agent from guessing. Give it a reasoning loop.**
4
4
 
5
- Without a protocol, AI agents guess — they hallucinate fixes, ignore architecture rules, fail silently, and lose context across a long session. SyncLoop solves this by wiring a strict 7-stage reasoning loop directly into your agent via MCP, so every task goes through sense → plan → act → validate → learn, every turn.
5
+ AI coding agents hallucinate fixes, ignore your architecture, lose context in long sessions, and repeat the same mistakes. SyncLoop wires a 7-stage self-correcting loop into your agent via MCP — sense → plan → act → validate → learn — every turn, automatically.
6
6
 
7
- Works with **GitHub Copilot**, **Cursor**, and **Claude Code** — any client that supports [Model Context Protocol](https://modelcontextprotocol.io/).
7
+ Works with **GitHub Copilot**, **Cursor**, and **Claude Code**.
8
8
 
9
9
  ---
10
10
 
11
- ## Why it matters
11
+ ## What changes for you
12
12
 
13
- | Without SyncLoop | With SyncLoop |
14
- |------------------|---------------|
15
- | Agent jumps straight to coding | Agent senses state and gaps first |
16
- | Fixes symptoms, not root causes | Diagnoses root cause before patching |
17
- | Ignores architecture layers | Enforces layer rules on every change |
18
- | Loses context in long sessions | Compresses and clears context each cycle |
19
- | Repeats the same mistakes | Learns from failures, persists heuristics |
20
- | No self-correction on test failures | Retries with targeted patches (max 5 iterations) |
13
+ | Problem | How SyncLoop fixes it |
14
+ |---------|----------------------|
15
+ | Agent breaks your architecture | Layer rules enforced on every change |
16
+ | Same bug reappears after agent "fixes" it | Agent retries with targeted patches, max 5 attempts, then escalates |
17
+ | Agent loses track in long sessions | Context compressed after each cycle — stale data discarded |
18
+ | Agent repeats failed approaches | Failed approaches pruned and recorded as hard constraints |
19
+ | Tests modified to pass | Agent is hardcoded to fix source code, never tests |
20
+ | No record of what the agent did or why | Structured reports and backlog tasks generated automatically |
21
21
 
22
22
  ---
23
23
 
24
24
  ## Quick Start
25
25
 
26
- Add to your MCP client configuration:
26
+ ### 1. Add to your MCP config
27
27
 
28
28
  ```json
29
29
  {
@@ -36,173 +36,115 @@ Add to your MCP client configuration:
36
36
  }
37
37
  ```
38
38
 
39
- That's it. Your agent now runs the full SyncLoop protocol on every turn.
39
+ > **Windows (VS Code):** use `"command": "npx.cmd"` — VS Code spawns without a shell on Windows.
40
40
 
41
- ### Where to add the config
42
-
43
- | Client | Config location |
44
- |--------|----------------|
41
+ | Client | Where to add it |
42
+ |--------|-----------------|
45
43
  | **VS Code (Copilot)** | `.vscode/mcp.json` or Settings → MCP Servers |
46
44
  | **Cursor** | Settings → MCP Servers |
47
45
  | **Claude Desktop** | `claude_desktop_config.json` |
48
46
  | **Claude Code** | `claude_code_config.json` or `--mcp-config` flag |
49
47
 
50
- ---
51
-
52
- ## How the Agent Loop Works
53
-
54
- Every agent turn runs the same 7-stage loop — no shortcuts:
55
-
56
- ```
57
- SENSE → GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT
58
- ```
59
-
60
- ### Stage by stage
61
-
62
- **1. SENSE**
63
- Before touching any code, the agent reads the current codebase state and identifies:
64
- - what needs to change
65
- - what could break
66
- - what context is still missing
67
-
68
- It will not proceed until it has enough information to act safely.
48
+ Done. Your agent now has access to the full protocol, pattern registry, and validation gates.
69
49
 
70
- **2. GKP — Generated Knowledge Pack**
71
- The agent routes through a pattern registry to pull only the constraints, risks, and implementation
72
- examples relevant to this specific task. Raw files are not carried forward — only a compressed,
73
- task-scoped context bundle is produced.
50
+ ### 2. Bootstrap to your project (optional)
74
51
 
75
- **3. DECIDE + ACT**
76
- The agent selects one of three operational modes and executes immediately:
52
+ Run the `bootstrap` prompt so the agent scans your codebase and populates protocol files with your real commands, architecture layers, and stack info.
77
53
 
78
- | Mode | When | What the agent does |
79
- |------|------|---------------------|
80
- | **INTACT-STABILIZE** | System is healthy | Harden types, add tests, improve docs |
81
- | **BROKEN-EXPAND** | Something is broken | Patch the root cause with minimal surface area |
82
- | **OVERDENSE-SPLIT** | Code is too complex | Decompose before adding anything new |
54
+ ### 3. Scaffold files for offline use (optional)
83
55
 
84
- Plan and action happen in the same step — no plans without execution.
56
+ Use the `init` tool to write protocol files directly into your repo:
85
57
 
86
- **4. CHALLENGE-TEST**
87
- Two validation gates run in a loop until everything passes or the retry budget runs out (max 5):
88
-
89
- 1. **ENV gate** — type safety, test coverage, layer integrity, complexity thresholds, debug hygiene
90
- 2. **NEIGHBOR gate** — shape compatibility across modules, boundary exports, cross-module contracts
91
-
92
- Failures are classified before any fix is attempted:
93
-
94
- | Class | Signal | What happens |
95
- |-------|--------|--------------|
96
- | **Micro** | Error text directly explains fix (missing return type, stray `print()`) | Fixed in-place, no budget consumed |
97
- | **Macro** | Root cause needs diagnosis (test failure, layer violation) | Patch cycle runs, consumes 1 of 5 retries |
98
-
99
- If the same failure recurs 3 times, the approach is pruned and the agent re-enters planning
100
- with a hardcoded constraint against repeating it. If it was already pruned once, the agent escalates.
101
-
102
- **5. UPDATE**
103
- Once all gates pass, state transitions are committed: changed files, updated contracts, modified patterns.
104
-
105
- **6. LEARN**
106
- Lessons from the cycle are persisted so they carry into future turns:
107
- - Quick fix → added as a row in the auto-fixes or common errors table
108
- - New reusable approach → written into the matching pattern spec
58
+ ```
59
+ Use the sync_loop init tool — choose: copilot, cursor, claude, or all
60
+ ```
109
61
 
110
- **7. REPORT**
111
- Non-trivial tasks produce a structured session summary: what changed, which gates passed, what was learned.
112
- Skipped for trivial one-liners.
62
+ This generates agent definitions, instruction files, and a canonical `.agent-loop/` folder with the full protocol. Useful for CI, offline work, or customization.
113
63
 
114
64
  ---
115
65
 
116
- ## Context Compaction
66
+ ## Use Cases
117
67
 
118
- Long coding sessions degrade agent quality when too much raw context accumulates.
119
- SyncLoop actively manages this with two strategies:
68
+ ### "Fix this bug without breaking anything else"
120
69
 
121
- **State Collapse — after a successful cycle**
122
- Everything is summarised into a compact checkpoint. Only that checkpoint enters the next SENSE stage.
123
- Raw history is discarded.
70
+ The agent reads the codebase first (SENSE), pulls only the relevant constraints (GKP), patches the root cause (DECIDE+ACT), then runs type checks + test gates + neighbor checks in a loop until everything passes (CHALLENGE-TEST). If the same fix fails 3 times, it's pruned and the agent tries a different approach.
124
71
 
125
- **Branch Pruning — on repeated failure**
126
- When the same error recurs 3 times, the failing approach is reverted and a constraint is recorded:
127
- "do not retry approach X". The agent re-enters DECIDE with that lesson injected.
72
+ ### "Refactor this module safely"
128
73
 
129
- This keeps the agent sharp in long sessions instead of degrading.
130
-
131
- ---
74
+ Pattern R1 kicks in: the agent plans the moves, executes them, validates all imports and cross-module contracts, and documents what changed. It won't mix refactoring with feature changes in the same patch.
132
75
 
133
- ## Pattern System
76
+ ### "Add an API endpoint"
134
77
 
135
- SyncLoop routes implementation decisions through a structured registry rather than letting the agent free-associate.
78
+ Patterns R3 (API contracts) and P5 (transport routes) route the agent to use typed request/response models, proper error envelopes, and enforce that no business logic leaks into the route handler.
136
79
 
137
- ### Pattern families
80
+ ### "This session is getting long and the agent is getting confused"
138
81
 
139
- | ID | What it covers |
140
- |----|----------------|
141
- | **P1–P11** | Port/adapter, domain modules, background tasks, transport routes, dependency injection, typed models, enum safety, error handling, type hints, service orchestration, config isolation |
142
- | **R1** | 4-phase safe refactoring: plan → execute → validate → document |
143
- | **R2** | Full test pyramid: unit, integration, API — fixtures, factories, mocks, naming conventions |
144
- | **R3** | API boundary contracts: typed request/response models, error envelopes, versioning |
82
+ SyncLoop compresses context after each successful cycle (State Collapse) and discards raw history. Only a compact checkpoint enters the next turn. The agent stays sharp instead of degrading.
145
83
 
146
- ### How pattern routing works
84
+ ### "I want to plan work but not implement it yet"
147
85
 
148
- Inside GKP, the agent:
149
- 1. Scans pattern triggers (`"Use when: moving a file"`, `"Use when: adding an endpoint"`)
150
- 2. Routes to the matching spec
151
- 3. Extracts constraints and examples for the active task only
152
- 4. Checks learned tables for known pitfalls and auto-fixes
153
- 5. Compresses to a minimal action context
154
-
155
- This makes decisions consistent across the session and prevents architecture drift.
86
+ The REPORT stage routes investigations to `docs/backlog/` as structured task files with priority, Action Plan, and acceptance criteria — separate from completed-work reports in `docs/reports/`.
156
87
 
157
88
  ---
158
89
 
159
- ## Testing Approach
90
+ ## The 7-Stage Loop
91
+
92
+ Every turn follows this sequence — no shortcuts, no skipped stages:
160
93
 
161
- Tests are run in order: changed files first → adjacent modules → full suite.
162
- The agent never modifies tests to make them pass. If a test fails, the source is fixed.
94
+ ```
95
+ SENSE → GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT
96
+ ```
163
97
 
164
- **Failure handling:**
165
- - Missing return types, stray debug calls → fixed inline, no retry budget spent
166
- - Real test failures or layer violations → root-cause diagnosis → targeted patch → retry gate
98
+ | Stage | What the agent does |
99
+ |-------|---------------------|
100
+ | **SENSE** | Reads codebase state, identifies gaps, won't proceed until context is sufficient |
101
+ | **GKP** | Routes through pattern registry, pulls only relevant constraints, compresses context |
102
+ | **DECIDE+ACT** | Selects mode (stabilize / fix / decompose), produces plan, executes immediately |
103
+ | **CHALLENGE-TEST** | Runs ENV gates (types, tests, layers) + NEIGHBOR gates (shapes, boundaries) in a loop |
104
+ | **UPDATE** | Commits state transitions — files changed, contracts updated |
105
+ | **LEARN** | Persists lessons to pattern tables for future turns |
106
+ | **REPORT** | Writes a report (completed work) or backlog task (deferred work) or skips (trivial) |
167
107
 
168
- **Test pyramid targets:** ≥70% unit, ≤20% integration, ≤10% API.
108
+ **Self-correction:** Test failures and layer violations trigger a patch → retry loop (max 5). Trivial issues (missing type, stray debug call) are fixed in-place without consuming retries. Same failure 3× → approach pruned, lesson injected, agent re-plans.
169
109
 
170
110
  ---
171
111
 
172
- ## Guardrails
112
+ ## What Gets Scaffolded
173
113
 
174
- The agent is hardcoded never to:
114
+ | Target | Files generated |
115
+ |--------|----------------|
116
+ | `copilot` | `.agent-loop/` + `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` + `.github/agents/SyncLoop*.agent.md` + `.github/skills/diagnose-failure/SKILL.md` |
117
+ | `cursor` | `.agent-loop/` + `.cursor/rules/*.md` |
118
+ | `claude` | `.agent-loop/` + `CLAUDE.md` + `.claude/rules/*.md` + `.claude/agents/SyncLoop*.md` + `.claude/skills/diagnose-failure/SKILL.md` |
119
+ | `all` | All of the above + `AGENTS.md` + `docs/backlog/index.md` |
175
120
 
176
- - Modify tests to force them green
177
- - Remove type annotations to silence type errors
178
- - Bypass architecture layer boundaries
179
- - Change public APIs or contracts without explicit user approval
180
- - Mix refactoring with feature changes in the same patch
181
- - Skip validation after refactors, import moves, or interface changes
121
+ **Agents scaffolded** (Copilot + Claude):
122
+ - **SyncLoop** — Full 7-stage protocol agent
123
+ - **SyncLoop-Architect** — Read-only planning agent (SENSE → GKP → DECIDE+ACT only)
124
+ - **SyncLoop-Fixer** — Implementation agent (CHALLENGE-TEST → UPDATE → LEARN)
182
125
 
183
- If any of these are required to proceed, the agent stops and escalates.
126
+ **Skills scaffolded:**
127
+ - **diagnose-failure** — Failure diagnosis using the FEEDBACK loop
184
128
 
185
129
  ---
186
130
 
187
- ## What the MCP server exposes
188
-
189
- ### Resources
131
+ ## MCP Server Reference
190
132
 
191
- All protocol docs are served on-demand — the agent pulls only what it needs per stage.
133
+ ### Resources (on-demand protocol docs)
192
134
 
193
135
  | Resource | Content |
194
136
  |----------|---------|
195
- | `reasoning-kernel` | Full 7-stage loop, transition map, stage details, context clearage |
196
- | `feedback` | Failure diagnosis, patch contract, micro-loop, branch pruning, learning |
197
- | `validate-env` | Stage 1 gates: types, tests, layers, complexity, debug hygiene |
198
- | `validate-n` | Stage 2 gates: shape compatibility, boundaries, bridge contracts |
199
- | `patterns` | Pattern routing index, GKP table, auto-fixes, heuristics, pruning records |
200
- | `glossary` | Canonical domain terminology and naming rules |
201
- | `code-patterns` | P1–P11 implementation patterns with examples |
202
- | `testing-guide` | Full test strategy: pyramid, fixtures, factories, mocks, parametrize |
203
- | `refactoring-workflow` | 4-phase refactoring checklist |
204
- | `api-standards` | Boundary contracts: typed models, error envelopes, versioning |
205
- | `protocol-summary` | Condensed ~50-line overview for system-prompt injection |
137
+ | `reasoning-kernel` | Full 7-stage loop, transition map, context clearage |
138
+ | `feedback` | Failure diagnosis, patch protocol, branch pruning |
139
+ | `validate-env` | Stage 1: types, tests, layers, complexity, debug hygiene |
140
+ | `validate-n` | Stage 2: shapes, boundaries, bridge contracts |
141
+ | `patterns` | Pattern routing index, auto-fixes, heuristics |
142
+ | `code-patterns` | P1–P11 implementation patterns |
143
+ | `testing-guide` | Test pyramid, fixtures, factories, mocks |
144
+ | `refactoring-workflow` | 4-phase safe refactoring checklist |
145
+ | `api-standards` | Boundary contracts, typed models, error envelopes |
146
+ | `glossary` | Domain terminology and naming rules |
147
+ | `protocol-summary` | Condensed ~50-line overview |
206
148
  | `agents-md` | AGENTS.md entrypoint template |
207
149
  | `overview` | File index and framework overview |
208
150
 
@@ -216,33 +158,11 @@ All protocol docs are served on-demand — the agent pulls only what it needs pe
216
158
 
217
159
  | Prompt | Description |
218
160
  |--------|-------------|
219
- | `bootstrap` | Wire SyncLoop to your actual project — scans codebase, populates real commands and architecture |
161
+ | `bootstrap` | Scan your codebase and wire SyncLoop to your real architecture |
220
162
  | `protocol` | Condensed protocol for direct system-prompt injection |
221
163
 
222
164
  ---
223
165
 
224
- ## Optional: scaffold files into your project
225
-
226
- For offline use, CI, or customisation, the full protocol can be written into your repo:
227
-
228
- ```
229
- Use the sync_loop init tool — choose: copilot, cursor, claude, or all
230
- ```
231
-
232
- | Target | Files generated |
233
- |--------|----------------|
234
- | `copilot` | `.agent-loop/` + `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` |
235
- | `cursor` | `.agent-loop/` + `.cursor/rules/*.md` with frontmatter |
236
- | `claude` | `.agent-loop/` + `CLAUDE.md` + `.claude/rules/*.md` |
237
- | `all` | All of the above + `AGENTS.md` |
238
-
239
- After scaffolding, use the `bootstrap` prompt so the agent scans your codebase and populates
240
- the generated files with real validation commands, architecture layers, and module boundaries.
241
-
242
- Platform instruction files are lightweight wrappers that delegate to `.agent-loop/*` canonical docs.
243
-
244
- ---
245
-
246
166
  ## Development
247
167
 
248
168
  ```bash
@@ -251,8 +171,6 @@ npm run typecheck
251
171
  npm test
252
172
  ```
253
173
 
254
- `npm test` runs a full TypeScript build first, then executes the automated test suite.
255
-
256
174
  ## License
257
175
 
258
176
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oleksandr.rudnychenko/sync_loop",
3
- "version": "0.3.7",
3
+ "version": "0.3.8",
4
4
  "type": "module",
5
5
  "description": "Self-correcting 7-stage agent reasoning loop (SENSE→GKP→DECIDE+ACT→CHALLENGE-TEST→UPDATE→LEARN→REPORT). MCP server + CLI that scaffolds instruction files for GitHub Copilot, Cursor, and Claude Code.",
6
6
  "bin": {