@oleksandr.rudnychenko/sync_loop 0.2.1

package/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/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": {
+    "syncloop": {
+      "command": "npx",
+      "args": ["-y", "syncloop"]
+    }
+  }
+}
+```
+
+### 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 syncloop 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/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/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.