@oleksandr.rudnychenko/sync_loop 0.2.5 → 0.3.2

package/dist/src/template/AGENTS.md

@@ -0,0 +1,157 @@
+# SyncLoop — {Project Name}
+
+Main entrypoint for AI agents working on this codebase.
+Routes into `.agent-loop/` for reasoning protocol, validation, feedback, and learning.
+
+**DO NOT MOVE THIS FILE TO DOCS/**. Keep it in the project root.
+
+---
+
+## 1. Project Identity
+
+{Brief project description — what it does, who it serves.}
+
+| Layer | Stack |
+|-------|-------|
+| Backend | {language, framework, runtime, database} |
+| Frontend | {framework, build tool, language, UI library} |
+| Infra | {hosting, CI/CD, object storage, caching} |
+
+**Architecture source of truth:** {path to architecture doc} — but code is authoritative when docs conflict.
+
+---
+
+## 2. SyncLoop Protocol
+
+Every turn follows a **7-stage protocol**:
+
+```
+1) SENSE ↔ 2) GKP
+        ↓
+3) DECIDE+ACT
+        ↓
+4) CHALLENGE-TEST
+   ├─ Stage 1: ENV   (validate-env.md)
+   └─ Stage 2: NEIGHBOR (validate-n.md)
+        ↓
+5) UPDATE
+        ↓
+6) LEARN
+        ↓
+7) REPORT
+```
+
+**Inner loops:**
+1. **SENSE ↔ GKP**: gather and compress context until sufficient
+2. **CHALLENGE-TEST → FEEDBACK → patch → retry**: iterate until gates pass (max 5)
+
+---
+
+## 3. Operational Modes
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| **INTACT-STABILIZE** | System is healthy | Harden quality, docs, and test confidence |
+| **BROKEN-EXPAND** | Defect or regression is present | Fix root cause with minimal safe surface area |
+| **OVERDENSE-SPLIT** | Complexity exceeds maintainability threshold | Decompose into smaller units before feature expansion |
+
+Mode is selected in DECIDE+ACT and can change after each validation cycle.
+
+---
+
+## 4. Architecture Guardrails
+
+### Layer Architecture
+
+```
+Routes → Services → Repositories → Libs
+```
+
+{Replace with actual project layers. Map directories to layer roles.}
+
+| Layer | Directory | Rules |
+|-------|-----------|-------|
+| **Routes** | `{path}` | Transport/boundary only. No business logic. |
+| **Services** | `{path}` | Business orchestration. Domain logic lives here. |
+| **Repositories** | `{path}` | Data access contracts. |
+| **Libs** | `{path}` | Infrastructure utilities. No imports from app modules. |
+
+### Cross-Layer Rules
+
+- **Never** import across incompatible layers (e.g., infra importing domain)
+- **Never** bypass the service layer from transport/route handlers
+- **Never** change public APIs without explicit approval
+- **Never** introduce sync calls in an async codebase (or vice versa)
+
+{Add project-specific cross-layer rules here.}
+
+---
+
+## 5. Validation Commands
+
+{Fill in with actual project commands after bootstrap.}
+
+```bash
+# Type check
+{typecheck command}
+
+# Lint & format
+{lint command}
+
+# Tests (all)
+{test command}
+
+# Tests (targeted)
+{targeted test command}
+
+# Install deps
+{install command}
+```
+
+---
+
+## 6. Key Domain Terms
+
+{Fill in during bootstrap — see [glossary.md](.agent-loop/glossary.md) for canonical definitions.}
+
+| Term | Model / Location | Description |
+|------|------------------|-------------|
+| {Term} | {file path} | {what it represents} |
+
+---
+
+## 7. Core SyncLoop Components
+
+| Component | File | Role |
+|-----------|------|------|
+| Protocol kernel | [.agent-loop/reasoning-kernel.md](.agent-loop/reasoning-kernel.md) | Master loop and execution schema |
+| Pattern registry | [.agent-loop/patterns.md](.agent-loop/patterns.md) | Pattern routing + learned fixes |
+| Pattern specs | [.agent-loop/patterns/](.agent-loop/patterns/) | Detailed implementation playbooks |
+| Domain vocabulary | [.agent-loop/glossary.md](.agent-loop/glossary.md) | Canonical terms and naming |
+| ENV validation | [.agent-loop/validate-env.md](.agent-loop/validate-env.md) | NFR gates |
+| NEIGHBOR validation | [.agent-loop/validate-n.md](.agent-loop/validate-n.md) | Shape/boundary/bridge checks |
+| Feedback loop | [.agent-loop/feedback.md](.agent-loop/feedback.md) | Failure diagnosis + patching |
+
+---
+
+## 8. Non-Negotiable Rules
+
+- ❌ Never modify tests only to force a pass result
+- ❌ Never suppress typing or validation just to remove errors
+- ❌ Never change public contracts without explicit approval
+- ❌ Never bypass architecture boundaries for convenience
+
+{Add project-specific rules here (e.g., multi-tenant isolation, audit requirements).}
+
+If uncertain, choose isolated and reversible changes.
+
+---
+
+## 9. Reporting & Artifacts
+
+- Reports: `docs/reports/YYYY-MM-DD-{slug}.md`
+- Artifacts: `docs/reports/artifacts/`
+- Learning memory: `.agent-loop/patterns.md` and `.agent-loop/patterns/*.md`
+
+Create reports for non-trivial work (multi-file refactor, root-cause fix, architecture change).
+

package/dist/src/template/README.md

@@ -0,0 +1,144 @@
+# SyncLoop Setup Guide
+
+This directory is a reusable template for bootstrapping SyncLoop into an existing codebase.
+
+---
+
+## Primary: MCP (recommended)
+
+Add the SyncLoop MCP server to your AI coding client. The agent gets the full protocol on-demand — no file scaffolding needed.
+
+```json
+{
+  "mcpServers": {
+      "sync_loop": {
+      "command": "npx",
+         "args": ["-y", "-p", "@oleksandr.rudnychenko/sync_loop", "sync_loop"]
+    }
+  }
+}
+```
+
+### Where to add MCP config
+
+| Client | Config location |
+|--------|----------------|
+| **VS Code (Copilot)** | `.vscode/mcp.json` or Settings → MCP Servers |
+| **Cursor** | Settings → MCP Servers |
+| **Claude Desktop** | `claude_desktop_config.json` |
+| **Claude Code** | `claude_code_config.json` or `--mcp-config` flag |
+
+Once connected, the agent has access to all protocol resources, the `init` tool for scaffolding, and the `bootstrap` prompt for project wiring.
+
+---
+
+## Alternative: Scaffold Files
+
+If you want the protocol files in your project (for offline use, customization, or CI), use the `init` tool via MCP or manually copy from this template.
+
+### Via MCP (ask the agent)
+
+Ask: "Use the sync_loop init tool to scaffold files for [copilot/cursor/claude/all] into this project"
+
+Before calling `init`, the agent should ask:
+"Which SyncLoop target platform should I scaffold: `copilot`, `cursor`, `claude`, or `all`?"
+
+### Manual Copy
+
+1. Copy `.agent-loop/` into your project root
+2. Copy `AGENTS.md` into your project root
+3. Run the bootstrap prompt below to wire to your project
+
+---
+
+## What This Setup Produces
+
+After bootstrap, the project should have:
+1. A root `AGENTS.md` aligned to the actual repository architecture
+2. A `.agent-loop/` pack with project-aware validation commands and routing
+3. A patterns index tied to real modules/services/contracts
+4. A glossary with canonical domain terms used in the repo
+
+The protocol itself remains generic:
+- SENSE ↔ GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT
+
+---
+
+## Bootstrap Prompt (Copy/Paste)
+
+Use this prompt with your coding agent in the target repository:
+
+```md
+Initialize and wire this SyncLoop framework to the current repository.
+
+Requirements:
+1) Scan the full codebase to understand:
+   - folder/module structure
+   - runtime stack and libraries/frameworks in use
+   - test/build/typecheck/lint commands
+   - architecture boundaries and dependency flow
+
+2) Update root AGENTS.md and .agent-loop docs so they reference the actual project:
+   - keep protocol abstractions and stage flow intact
+   - replace placeholders with project-specific references where needed
+   - include real validation commands for this repo
+   - include real module/layer boundaries and guardrails
+
+3) Build/refresh these artifacts:
+   - .agent-loop/patterns.md routing index
+   - .agent-loop/glossary.md canonical terms
+   - .agent-loop/validate-env.md with actual gate commands
+   - .agent-loop/validate-n.md with real neighbor/contract checks
+   - .agent-loop/feedback.md escalation and learn-routing
+
+4) Preserve safety constraints:
+   - do not weaken validation gates
+   - do not change public APIs unless explicitly requested
+   - do not edit tests only to force passing status
+
+5) Output:
+   - summary of files changed
+   - detected stack/tools/commands
+   - unresolved ambiguities requiring user input
+
+Work end-to-end and apply edits directly.
+```
+
+---
+
+## Recommended Execution Sequence
+
+1. **Inventory**
+   - Parse manifests/lockfiles and CI configs
+   - Identify source roots, module boundaries, and docs locations
+
+2. **Command Discovery**
+   - Detect canonical commands for typecheck/tests/lint/build
+   - Prefer existing scripts over inferred commands
+
+3. **Architecture Mapping**
+   - Map route/service/repository/lib equivalents for this codebase
+   - Identify forbidden dependency directions
+
+4. **Doc Wiring**
+   - Update `AGENTS.md` first (entrypoint)
+   - Align `.agent-loop/*` files with discovered project facts
+   - Keep generic reasoning protocol unchanged
+
+5. **Validation Pass**
+   - Run the detected validation commands
+   - Fix only issues introduced by wiring changes
+
+6. **Handoff**
+   - Provide concise report and any follow-up actions
+
+---
+
+## Acceptance Checklist
+
+- [ ] `AGENTS.md` points to the right local docs and architecture
+- [ ] `.agent-loop/validate-env.md` uses repo-true commands
+- [ ] `.agent-loop/patterns.md` routes to real project patterns
+- [ ] `.agent-loop/glossary.md` reflects actual domain vocabulary
+- [ ] No direct references to unrelated projects
+- [ ] Protocol and guardrails remain intact

package/dist/src/template/bootstrap-prompt.md

@@ -0,0 +1,37 @@
+Initialize and wire the SyncLoop reasoning protocol to the current repository.
+
+If SyncLoop target platform is not explicitly provided yet, ask the user first:
+"Which SyncLoop target platform should I scaffold: `copilot`, `cursor`, `claude`, or `all`?"
+
+Requirements:
+
+1) Scan the full codebase to understand:
+   - folder/module structure
+   - runtime stack and libraries/frameworks in use
+   - test/build/typecheck/lint commands
+   - architecture boundaries and dependency flow
+
+2) Update root AGENTS.md and .agent-loop docs so they reference the actual project:
+   - keep protocol abstractions and stage flow intact
+   - replace placeholders with project-specific references where needed
+   - include real validation commands for this repo
+   - include real module/layer boundaries and guardrails
+
+3) Build/refresh these artifacts:
+   - .agent-loop/patterns.md routing index
+   - .agent-loop/glossary.md canonical terms
+   - .agent-loop/validate-env.md with actual gate commands
+   - .agent-loop/validate-n.md with real neighbor/contract checks
+   - .agent-loop/feedback.md escalation and learn-routing
+
+4) Preserve safety constraints:
+   - do not weaken validation gates
+   - do not change public APIs unless explicitly requested
+   - do not edit tests only to force passing status
+
+5) Output:
+   - summary of files changed
+   - detected stack/tools/commands
+   - unresolved ambiguities requiring user input
+
+Work end-to-end and apply edits directly.

package/dist/src/template/protocol-summary.md

@@ -0,0 +1,54 @@
+# SyncLoop Agent Protocol
+
+Self-correcting 7-stage reasoning loop for every task.
+
+## Protocol
+
+```
+SENSE → GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT
+```
+
+### Stages
+
+1. **SENSE** — Detect current state, issues, context gaps
+2. **GKP** — Gather and compress relevant knowledge (patterns, constraints, risks)
+3. **DECIDE+ACT** — Select mode, plan action, execute immediately
+4. **CHALLENGE-TEST** — Run 2-stage validation (ENV gates + NEIGHBOR checks)
+5. **UPDATE** — Commit state transitions
+6. **LEARN** — Persist fixes and patterns
+7. **REPORT** — Session summary (skip if trivial)
+
+### Inner Loops
+
+1. **SENSE ↔ GKP** — cycle until relevant context gathered and compressed
+2. **CHALLENGE-TEST → FEEDBACK → patch → retry** — iterate until gates pass (max 5)
+
+### Modes
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| **INTACT-STABILIZE** | All gates pass | Harden quality, tests, docs |
+| **BROKEN-EXPAND** | Issues detected | Fix root cause, minimal surface |
+| **OVERDENSE-SPLIT** | Complexity high | Decompose before expanding |
+
+### Validation (CHALLENGE-TEST)
+
+- **Stage 1: ENV** — types, tests, layers, complexity, debug hygiene
+- **Stage 2: NEIGHBOR** — shapes, boundaries, bridges
+- Classify failures: **Micro** (fix in-place, no budget cost) vs **Macro** (→ feedback loop, -1 of 5 retries)
+- Max 5 macro iterations; branch prune on 3× same error
+
+### Context Management
+
+- Compress after GKP — don't carry raw files forward
+- State Collapse after LEARN — checkpoint summary + discard history
+- Per-stage loading: only read files relevant to current stage
+
+### Guardrails
+
+- ❌ Never modify tests to force pass
+- ❌ Never suppress types to fix errors
+- ❌ Never change public API without approval
+- ❌ Never bypass architecture layers
+
+Full protocol details available via SyncLoop MCP resources or in `.agent-loop/` directory.

package/dist/src/template/wiring/agents-claude.md

@@ -0,0 +1,203 @@
+---
+name: "SyncLoop"
+description: "Self-correcting 7-stage reasoning agent. Runs SENSE → GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT on every task. Use for all coding tasks on this codebase."
+---
+
+<!--
+Spec: Claude Code Subagent  (.claude/agents/*.md)
+
+Frontmatter fields:
+  name:         string   – agent identifier (required)
+  description:  string   – when to auto-invoke this subagent; be specific (required)
+  model:        string   – override model; default inherits from session (optional)
+  color:        string   – UI label color (optional)
+  tools:        array    – restrict available tools; omit for full access (optional)
+                          Read | Write | Edit | Bash | Glob | Grep | LS
+                          Task | WebFetch | WebSearch | TodoRead | TodoWrite
+
+Claude auto-invokes this agent when the task description matches `description`.
+Omitting `tools` grants all tools. Restricting tools increases isolation for
+high-risk or focused subagents.
+-->
+
+You are the SyncLoop agent for this codebase.
+
+Execute the **7-stage SyncLoop loop** on every turn before any action.
+Full authoritative spec: `.agent-loop/reasoning-kernel.md`
+
+---
+
+## Protocol
+
+```
+SENSE → GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT
+```
+
+**Two inner loops:**
+1. **SENSE ↔ GKP** — cycle until context is gathered and compressed
+2. **CHALLENGE-TEST → FEEDBACK → patch → retry** — iterate until all gates pass (max 5 macro iterations)
+
+---
+
+## Spec Files
+
+Load these at the indicated stage. **Scoped loading only** — never load all at once.
+
+| File | Purpose | Load At |
+|------|---------|---------|
+| `.agent-loop/reasoning-kernel.md` | Master loop, full stage detail, transition map, output schema | SENSE |
+| `.agent-loop/patterns.md` | Pattern routing index, Architecture Baseline, Auto-Fixes, Common Errors | GKP |
+| `.agent-loop/patterns/code-patterns.md` | P1–P11 code architecture patterns | GKP |
+| `.agent-loop/patterns/testing-guide.md` | R2 — test patterns, fixtures, mocks (use for test tasks) | GKP |
+| `.agent-loop/patterns/refactoring-workflow.md` | R1 — 4-phase refactoring checklist (use for refactor tasks) | GKP |
+| `.agent-loop/patterns/api-standards.md` | R3 — boundary contracts, typed models, error envelopes (use for API tasks) | GKP |
+| `.agent-loop/patterns/mcp-patterns.md` | M1–M5 — MCP server bootstrap, resources, tools, prompts, lifecycle | GKP |
+| `.agent-loop/validate-env.md` | Stage 1 gates: types, tests, layers, complexity, debug hygiene | CHALLENGE-TEST |
+| `.agent-loop/validate-n.md` | Stage 2 gates: shapes, boundaries, bridges | CHALLENGE-TEST |
+| `.agent-loop/feedback.md` | Failure diagnosis, patch protocol, branch pruning | FEEDBACK |
+| `.agent-loop/glossary.md` | Canonical domain terms — resolve ambiguous words here | SENSE/GKP |
+
+---
+
+## Reasoning Kernel (embedded)
+
+### Loop
+
+```
+  ┌──────────────────────────────────────────────────────────────┐
+  │   ┌─────────┐     ┌─────────┐                               │
+  │   │ 1 SENSE │◄───►│ 2 GKP   │  ← inner loop: gather+compress│
+  │   └────┬────┘     └────┬────┘                               │
+  │        └───────┬───────┘                                    │
+  │                ▼                                            │
+  │        ┌──────────────┐                                     │
+  │        │ 3 DECIDE+ACT │  ← select mode + execute           │
+  │        └──────┬───────┘                                     │
+  │               ▼                                             │
+  │   ┌───────────────────────┐                                 │
+  │   │ 4 CHALLENGE-TEST      │  ← validate + fix loop (max 5) │
+  │   │   ├ validate-env.md   │                                 │
+  │   │   └ validate-n.md     │                                 │
+  │   └──────────┬────────────┘                                 │
+  │              ▼                                              │
+  │        ┌──────────┐                                         │
+  │        │ 5 UPDATE  │  ← commit state transitions           │
+  │        └─────┬────┘                                         │
+  │              ▼                                              │
+  │        ┌──────────┐                                         │
+  │        │ 6 LEARN   │  ← persist to patterns.md / specs     │
+  │        └────┬─────┘                                         │
+  │             ▼                                               │
+  │        ┌──────────┐                                         │
+  │        │ 7 REPORT  │  ← docs/reports/ (skip if trivial)    │
+  │        └──────────┘                                         │
+  └──────────────────────────────────────────────────────────────┘
+```
+
+### Modes
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| **INTACT-STABILIZE** | All gates pass, no issues | Harden: add tests, improve types, document |
+| **BROKEN-EXPAND** | Issues / defects detected | Fix: minimal patches, root cause first |
+| **OVERDENSE-SPLIT** | Complexity too high | Decompose: split files, extract modules |
+
+Mode selected in DECIDE+ACT. Can change after each validation cycle.
+
+### Stages (brief)
+
+1. **SENSE** — Extract current state, detect issues, identify context gaps. Cycle with GKP.
+2. **GKP** — Route into `patterns.md` → matching spec file. Compress. Don't carry raw files forward.
+3. **DECIDE+ACT** — Select mode. Produce Action Plan. Execute immediately (plan + act are one phase).
+4. **CHALLENGE-TEST** — Run `validate-env.md` then `validate-n.md`. Classify failures (see below). Loop until pass or budget exhausted.
+5. **UPDATE** — Commit state transitions. If new issue found → one more CHALLENGE-TEST pass.
+6. **LEARN** — Persist: quick fix → `patterns.md` table; deep pattern → `patterns/{spec}.md`; new term → `glossary.md`.
+7. **REPORT** — Write `docs/reports/YYYY-MM-DD-{slug}.md` for non-trivial work. Skip for single-file cosmetic fixes.
+
+### Failure Classification
+
+| Signal | Class | Action |
+|--------|-------|--------|
+| Type error on new code only | **Micro** | Fix in-place, no budget consumed |
+| Debug remnant (`console.log`, `breakpoint()`) | **Micro** | Remove, no budget consumed |
+| Unused import after refactor | **Micro** | Remove, no budget consumed |
+| Test failure | **Macro** | → `feedback.md`, consumes 1 of 5 iterations |
+| Layer violation | **Macro** | → `feedback.md`, consumes 1 of 5 iterations |
+| Shape mismatch across modules | **Macro** | → `feedback.md`, consumes 1 of 5 iterations |
+| Same micro-fix needed 3× | **→ Macro** | Escalate: systemic issue |
+
+**Micro budget:** max 2 micro-fixes per gate before escalating.
+**Macro budget:** 5 total iterations. Same error 3×: branch prune (see `feedback.md`).
+
+### Action Plan
+
+```
+ACTION PLAN:
+- Core:     [main logic change — files, functions]
+- Shell:    [boundary change — new params, exports, routes]
+- Neighbor: [affected modules — who calls this, who breaks]
+- Pattern:  [pattern ID(s) — e.g., P1+P10, R1, M3]
+- Risk:     [what could go wrong — rollback strategy]
+```
+
+---
+
+## Project Architecture
+
+| Stack | Languages | Frameworks |
+|-------|-----------|------------|
+| app | Unknown | Unknown |
+
+Full architecture and layer rules: `AGENTS.md`
+Canonical spec files: `.agent-loop/` directory
+
+---
+
+## Output Schema
+
+Every turn must use this exact structure:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SENSE
+[current state, detected issues, context gaps]
+
+MODE
+[INTACT-STABILIZE | BROKEN-EXPAND | OVERDENSE-SPLIT]
+
+GKP
+- Patterns: [IDs consulted, spec files read]
+- Constraints: [key constraints]
+- Risks: [key risks]
+
+ACTION (DECIDE+ACT)
+- Core: [main logic change]
+- Shell: [interface/boundary change]
+- Neighbor: [affected modules]
+- Pattern: [which IDs apply]
+
+CHALLENGE-TEST (iteration N/5)
+[PASS | FAIL — reason]
+
+UPDATE
+[files changed, state transitions]
+
+LEARN
+[what was persisted to patterns.md or patterns/*.md]
+
+REPORT
+[docs/reports/YYYY-MM-DD-{slug}.md — or "skipped (trivial)"]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Guardrails
+
+- ❌ Never modify tests to force a pass — fix source code
+- ❌ Never suppress types to remove errors — add correct types
+- ❌ Never change public APIs without explicit approval
+- ❌ Never implement logic in transport/boundary layers — delegate to core
+- ❌ Never import across incompatible layers
+- ❌ Never rename the package or binary in one place — update all references atomically
+- ❌ Uncertain about impact? Prefer isolated and reversible changes