@oleksandr.rudnychenko/sync_loop 0.3.2 → 0.3.3

package/dist/src/template/wiring/agents-github-architect.md

@@ -0,0 +1,94 @@
+---
+name: "SyncLoop-Architect"
+description: "SyncLoop subagent for planning and architecture. Runs SENSE → GKP → DECIDE+ACT. Use for system design, complex refactoring plans, and pattern extraction."
+argument-hint: "A feature or refactoring request to plan."
+tools:
+  - "read"
+  - "search"
+  - "web"
+---
+
+You are the SyncLoop Architect agent for this codebase.
+
+Your role is to execute the first half of the **7-stage SyncLoop loop**:
+`SENSE → GKP → DECIDE+ACT`
+
+You do NOT implement code. You produce an **Action Plan** and either:
+1. Hand it to the SyncLoop-Fixer agent for immediate implementation, OR
+2. Store it as a **backlog task** in `docs/backlog/` for later implementation.
+
+### Backlog Workflow
+
+When a task requires investigation and planning but is not ready for immediate implementation (complex, multi-step, needs approval, or lower priority), create a backlog task:
+
+1. Create a task file at `docs/backlog/YYYY-MM-DD-{slug}.md` with the Action Plan, context, and acceptance criteria
+2. Update `docs/backlog/README.md` index table — add a row with task number, title, priority (P0–P3), state (`planned`), creation date, and filename
+3. Report the backlog entry to the user
+
+Use backlog task format:
+
+```
+# {Task Title}
+
+**Priority:** P0 | P1 | P2 | P3
+**State:** planned
+**Created:** YYYY-MM-DD
+
+## Context
+[Why this task exists, what was discovered during investigation]
+
+## Action Plan
+- Core: [main logic change — files, functions]
+- Shell: [boundary change — new params, exports, routes]
+- Neighbor: [affected modules — who calls this, who breaks]
+- Pattern: [which IDs apply]
+- Risk: [what could go wrong — rollback strategy]
+
+## Acceptance Criteria
+- [ ] [Specific, verifiable condition]
+- [ ] [Another condition]
+```
+
+---
+
+## Spec Files to Load
+
+| File | Purpose | Load At |
+|------|---------|---------|
+| `.agent-loop/reasoning-kernel.md` | Master loop, full stage detail | SENSE |
+| `.agent-loop/patterns.md` | Pattern routing index, Architecture Baseline | GKP |
+| `.agent-loop/patterns/code-patterns.md` | P1–P11 code architecture patterns | GKP |
+| `.agent-loop/glossary.md` | Canonical domain terms | SENSE/GKP |
+
+---
+
+## Output Schema
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+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 PLAN (DECIDE+ACT)
+- Core: [main logic change — files, functions]
+- Shell: [boundary change — new params, exports, routes]
+- Neighbor: [affected modules — who calls this, who breaks]
+- Pattern: [which IDs apply]
+- Risk: [what could go wrong — rollback strategy]
+
+DISPOSITION
+[IMPLEMENT NOW → hand to SyncLoop-Fixer | BACKLOG → store in docs/backlog/]
+
+NEXT STEPS
+[If implementing: instructions for SyncLoop-Fixer]
+[If backlog: task file path + index update confirmation]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/dist/src/template/wiring/agents-github-fixer.md

@@ -0,0 +1,53 @@
+---
+name: "SyncLoop-Fixer"
+description: "SyncLoop subagent for implementation and validation. Runs CHALLENGE-TEST → UPDATE → LEARN. Use for executing Action Plans and fixing bugs."
+argument-hint: "An Action Plan to implement or a bug to fix."
+tools:
+  - "vscode"
+  - "execute"
+  - "read"
+  - "edit"
+  - "search"
+  - "todo"
+---
+
+You are the SyncLoop Fixer agent for this codebase.
+
+Your role is to execute the second half of the **7-stage SyncLoop loop**:
+`CHALLENGE-TEST → UPDATE → LEARN`
+
+You take an **Action Plan** (from the user or the Architect agent), implement it, and run the validation gates.
+
+---
+
+## Spec Files to Load
+
+| File | Purpose | Load At |
+|------|---------|---------|
+| `.agent-loop/reasoning-kernel.md` | Master loop, full stage detail | SENSE |
+| `.agent-loop/validate-env.md` | Stage 1 gates: types, tests, layers, complexity | 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 |
+
+---
+
+## Output Schema
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+IMPLEMENTATION
+[files changed, logic implemented]
+
+CHALLENGE-TEST (iteration N/5)
+[PASS | FAIL — reason]
+
+UPDATE
+[state transitions, commits]
+
+LEARN
+[what was persisted to patterns.md or patterns/*.md]
+
+REPORT
+[docs/reports/YYYY-MM-DD-{slug}.md — or "skipped (trivial)"]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

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

@@ -120,7 +120,19 @@ Mode selected in DECIDE+ACT. Can change after each validation cycle.
 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.
+7. **REPORT** — Route output: implemented + multi-file → `docs/reports/`; planned but not implemented → `docs/backlog/`; trivial → skip.
+
+### Report vs Backlog Routing
+
+```
+Work implemented this session?
+├─ YES + multi-file or architecture change → write docs/reports/YYYY-MM-DD-{slug}.md
+├─ YES + single-file cosmetic/docs-only    → skip
+├─ NO  + investigation/plan produced       → write docs/backlog/YYYY-MM-DD-{slug}.md + update index
+└─ NO  + trivial lookup/question           → skip
+```
+
+Reports = completed work. Backlog tasks = planned but unexecuted work. Never create both for the same task.
 
 ### Failure Classification
 
@@ -194,7 +206,7 @@ LEARN
 [what was persisted to patterns.md or patterns/*.md]
 
 REPORT
-[docs/reports/YYYY-MM-DD-{slug}.md — or "skipped (trivial)"]
+[docs/reports/YYYY-MM-DD-{slug}.md | docs/backlog/YYYY-MM-DD-{slug}.md — or "skipped (trivial)"]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 

package/dist/src/template/wiring/skills-diagnose-failure.md

@@ -0,0 +1,34 @@
+---
+name: "diagnose-failure"
+description: "Run the SyncLoop FEEDBACK loop to diagnose a test failure, type error, or layer violation. Use this when CHALLENGE-TEST fails."
+---
+
+# Diagnose Failure (SyncLoop FEEDBACK)
+
+You are executing the **FEEDBACK** stage of the SyncLoop protocol.
+
+## Instructions
+
+1. Read `.agent-loop/feedback.md` to understand the patch protocol and branch pruning rules.
+2. Analyze the failure (test output, type error, or layer violation).
+3. Classify the failure as **Micro** or **Macro**.
+4. Produce a patch.
+5. If this is the 3rd time the same error has occurred, trigger **Branch Prune** and revert the approach.
+
+## Output Schema
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DIAGNOSIS
+[Error analysis and classification: Micro vs Macro]
+
+PATCH PLAN
+[What needs to be changed to fix the error]
+
+EXECUTION
+[Apply the patch]
+
+NEXT STEPS
+[Instructions to re-run CHALLENGE-TEST]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oleksandr.rudnychenko/sync_loop",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
-  "description": "MCP server for the SyncLoop agent reasoning protocol - works with Copilot, Cursor, Claude Code",
+  "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.",
   "bin": {
     "sync_loop": "./bin/cli.js"
   },
@@ -30,15 +30,27 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
+    "model-context-protocol",
     "ai",
+    "ai-agent",
     "agent",
+    "agentic",
     "copilot",
+    "github-copilot",
     "cursor",
     "claude",
+    "claude-code",
+    "llm",
     "prompt-engineering",
     "coding-agent",
     "reasoning-loop",
-    "sync_loop"
+    "self-correcting",
+    "scaffolding",
+    "instructions",
+    "sync_loop",
+    "syncloop",
+    "devtools"
   ],
   "license": "MIT",
   "author": "oleksandr.rudnychenko",

package/src/template/.agent-loop/patterns/api-standards.md

@@ -19,76 +19,27 @@ Referenced from [../patterns.md](../patterns.md).
 
 ## Workflow for New Routes
 
-```
-1. Define Request/Response models in the module's models file
-2. Implement the route handler using those models
-3. Register the router in the app entrypoint with appropriate tags
-4. Run spec generation script
+1. Define Request and Response **typed models** in the module's models file — every field has a declared type and sensible defaults for optional fields
+2. Implement the route handler: parse input into the request model, resolve the service via dependency injection, call the service, and return the response model
+3. Register the router in the app entrypoint with appropriate semantic tags
+4. Run the spec generation script (OpenAPI, Swagger, or equivalent)
 5. Verify generated docs match expectations
-```
-
-### Example Route
-
-```python
-# models.py — typed boundary contracts
-@dataclass
-class CreateEntityRequest:
-    name: str
-    entity_type: str
-    metadata: dict[str, Any] = field(default_factory=dict)
-
-@dataclass
-class EntityResponse:
-    id: str
-    name: str
-    entity_type: str
-    status: str
-    created_at: str
-
-# routes.py — thin transport layer
-@router.post("/entities", response_model=EntityResponse)
-def create_entity(
-    data: CreateEntityRequest,
-    service: EntityService = Depends(get_service),
-) -> EntityResponse:
-    """Create a new entity for processing.
-
-    Validates input, delegates to service, returns created entity.
-    """
-    result = service.create(data)
-    return EntityResponse(
-        id=result.id,
-        name=result.name,
-        entity_type=result.entity_type,
-        status=result.status,
-        created_at=result.created_at.isoformat(),
-    )
-```
+
+### Route Handler Structure
+
+A route handler is a thin transport function. It declares the HTTP method and path, accepts a typed request model as input, resolves the service through the framework's dependency injection mechanism, delegates the business operation to the service, and returns a typed response model. The handler contains no business logic, conditionals, or data transformations beyond serialization.
 
 ---
 
 ## Error Envelope
 
-All error responses must follow a consistent structure:
-
-```python
-# Standard error response
-@dataclass
-class ErrorResponse:
-    error: str          # Machine-readable error code
-    message: str        # Human-readable description
-    details: dict = field(default_factory=dict)  # Optional context
-
-# Usage at route boundary
-@router.get("/entities/{entity_id}")
-def get_entity(entity_id: str, service = Depends(get_service)):
-    try:
-        return service.get(entity_id)
-    except NotFoundError as exc:
-        raise HTTPException(status_code=404, detail=str(exc))
-    except ValidationError as exc:
-        raise HTTPException(status_code=400, detail=str(exc))
-```
+All error responses must follow a consistent structure with three fields:
+
+- **error**: a machine-readable error code (string)
+- **message**: a human-readable description (string)
+- **details**: optional context dictionary for debugging
+
+At the route boundary, catch domain-specific exceptions (NotFoundError, ValidationError) and translate them to the appropriate HTTP status code plus an error envelope. Let unexpected exceptions propagate to a global handler that returns a generic 500-level response.
 
 ---
 

package/src/template/.agent-loop/patterns/code-patterns.md

@@ -9,34 +9,11 @@ Referenced from [../patterns.md](../patterns.md).
 
 Abstracts infrastructure behind protocol interfaces. Decouples domain logic from external systems.
 
-```python
-# Port (interface/protocol)
-class StoragePort(Protocol):
-    def search(
-        self,
-        collection: str,
-        query: str,
-        *,
-        filters: dict | None = None,
-        limit: int = 10,
-    ) -> list[Record]: ...
-
-# Adapter (concrete implementation)
-class DatabaseAdapter:
-    def __init__(self, client: DBClient) -> None:
-        self._client = client
-
-    def search(
-        self,
-        collection: str,
-        query: str,
-        *,
-        filters: dict | None = None,
-        limit: int = 10,
-    ) -> list[Record]:
-        # Implementation against real infrastructure
-        ...
-```
+Define a **Port** as an interface (or protocol/trait) that declares the operations a service needs — method names, parameter types, and return types — without any implementation details. The Port belongs to the domain layer and knows nothing about databases, HTTP, or file systems.
+
+Create an **Adapter** as a concrete class that implements the Port interface. Each adapter encapsulates the specifics of one external system (a database client, an HTTP API, a message queue). Multiple adapters can satisfy the same port.
+
+Services receive the port interface via constructor injection, never the adapter directly.
 
 **Key rules:**
 - Port lives in `libs/{component}/port.*`
@@ -56,17 +33,11 @@ Each domain module follows a consistent multi-file layout:
 | `routes.*` | Transport endpoints |
 | `tasks.*` | Background tasks (if async processing needed) |
 
-```python
-# services.py — business logic only, no transport concerns
-class OrderService:
-    def __init__(self, repository: OrderRepository) -> None:
-        self._repository = repository
+The **models** file defines data structures (classes, structs, or types) representing the core domain — entities with identity, value objects without identity, and any associated enums or constants.
+
+The **services** file contains business logic: methods that operate on models, enforce invariants, and coordinate between ports. Services never reference transport or serialization concerns.
 
-    def process(self, *, order_id: str) -> ProcessResult:
-        order = self._repository.get(order_id)
-        # business logic here
-        return ProcessResult(order_id=order.id, status="completed")
-```
+The **routes** file is the transport boundary — HTTP handlers, CLI entry points, or message consumers. Routes parse input, delegate to a service, and format the response. No business logic lives here.
 
 ---
 
@@ -74,219 +45,80 @@ class OrderService:
 
 Task handlers stay thin. Business logic always lives in services.
 
-```python
-# tasks.py — thin wrapper, delegates to service
-def process_order_task(runtime: TaskRuntime, order_id: str):
-    """Background task that delegates to service."""
-    service = runtime.order_service
-    service.update_status(order_id, status="processing")
-
-    try:
-        service.process(order_id=order_id)
-        service.update_status(order_id, status="completed")
-    except Exception as exc:
-        service.update_status(order_id, status="failed", error=str(exc))
-        raise
-```
+A task handler is a function or method invoked by a job queue or scheduler. It receives a runtime context (containing pre-wired service instances) and the task payload. The handler calls the appropriate service method, updates task status on success and failure, and re-raises exceptions for the queue's retry mechanism.
 
 **Key rules:**
 - Tasks never contain business logic
-- Dependencies injected via runtime, not imported directly
-- Always update status on success and failure
+- Dependencies injected via runtime context, not imported directly
+- Always update status on both success and failure paths
 
 ---
 
 ## P4 · App Context / Composition Root
 
-Centralized dependency wiring, initialized once at startup:
-
-```python
-@dataclass
-class AppContext:
-    config: Config
-    session_factory: SessionFactory
-    services: ServiceRegistry
-    logger: Logger
-
-_context: AppContext | None = None
+Centralized dependency wiring, initialized once at startup.
 
-def init_app_context(config: Config) -> AppContext:
-    global _context
-    if _context:
-        return _context
-    _context = AppContext(config=config, ...)
-    return _context
-
-def get_app_context() -> AppContext:
-    if _context is None:
-        return init_app_context(load_config())
-    return _context
-```
+Define an **AppContext** as a container (class or struct) holding all application-wide dependencies: configuration, database session factories, service registries, and loggers. A factory function creates the context once during startup, caching it as a module-level singleton. All subsequent access goes through a getter that returns the cached instance. This ensures consistent wiring and makes the full dependency graph visible in one place.
 
 ---
 
 ## P5 · Transport Route
 
-Routes only handle transport concerns; all logic delegated to services:
-
-```python
-router = APIRouter()
+Routes only handle transport concerns; all logic delegated to services.
 
-def get_service() -> OrderService:
-    ctx = get_app_context()
-    return OrderService(ctx.repository)
-
-@router.post("/orders")
-def create_order(
-    data: CreateOrderRequest,
-    service: OrderService = Depends(get_service),
-) -> OrderResponse:
-    result = service.create(data)
-    return OrderResponse(id=result.id, status=result.status)
-```
+A route handler performs three steps: (1) parse and validate the incoming request into a typed model, (2) resolve the appropriate service instance via dependency injection, and (3) call the service method and map the result to a typed response model. The handler never contains conditionals, loops, or data transformations beyond serialization.
 
 ---
 
 ## P6 · Typed Models
 
-Domain entities with explicit types and serialization:
-
-```python
-@dataclass(slots=True)
-class OrderItem:
-    product_id: str
-    quantity: int
-    unit_price: float
-    tags: list[str] = field(default_factory=list)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "product_id": self.product_id,
-            "quantity": self.quantity,
-            "unit_price": self.unit_price,
-            "tags": self.tags,
-        }
-```
+Domain entities with explicit types and serialization.
+
+Every data structure that crosses a boundary (API request, API response, database row, message payload) must be a typed model — a class, struct, or schema with named fields and declared types. Each model provides a serialization method (to dictionary, JSON, or equivalent) for transport. Use slot-based or frozen classes where the language supports them to prevent accidental mutation.
 
 ---
 
 ## P7 · Collection/Enum Safety
 
-Replace magic strings with typed enums:
+Replace magic strings with typed enums.
 
-```python
-class Collection(str, Enum):
-    ORDERS = "orders"
-    PRODUCTS = "products"
-    USERS = "users"
-
-# Usage: repository.query(Collection.ORDERS, ...)
-# NOT: repository.query("orders", ...)
-```
+Define an enum (or string enum / literal union) for any fixed set of values: collection names, status codes, category labels, entity types. All code references the enum member, never a raw string. This centralizes valid values in one declaration and makes invalid states unrepresentable.
 
 ---
 
 ## P8 · Error Handling
 
-Layered exception hierarchy with boundary translation:
-
-```python
-# Domain exceptions
-class DomainError(Exception):
-    """Base error for domain."""
-
-class NotFoundError(DomainError):
-    """Resource not found."""
-
-class ValidationError(DomainError):
-    """Invalid input or state."""
+Layered exception hierarchy with boundary translation.
 
-# Route-level translation
-@router.get("/orders/{order_id}")
-def get_order(order_id: str, service = Depends(get_service)):
-    try:
-        return service.get(order_id)
-    except NotFoundError as exc:
-        raise HTTPException(status_code=404, detail=str(exc))
-    except ValidationError as exc:
-        raise HTTPException(status_code=400, detail=str(exc))
-```
+Define a base domain exception class. Derive specific exceptions from it: `NotFoundError`, `ValidationError`, `ConflictError`, etc. Business logic raises domain exceptions only. At the transport boundary (route handler), catch domain exceptions and translate them to the appropriate HTTP status codes or error responses. Internal implementation errors (unexpected crashes) propagate to a global handler that returns a generic 500-level response.
 
 ---
 
 ## P9 · Type Hints Everywhere
 
-All code must have complete type annotations:
+All code must have complete type annotations.
 
-```python
-# ✅ Good — fully typed
-def process(
-    order_id: str,
-    *,
-    callback: Callable[..., Awaitable[Response]] | None = None,
-) -> tuple[str, dict[str, Any]] | None:
-    ...
-
-# ❌ Bad — missing annotations
-def process(order_id, callback=None):
-    ...
-```
-
-**Common type aliases:**
-```python
-SessionFactory = Callable[[], Session]
-Filters = Mapping[str, Any]
-```
+Every function signature declares parameter types and return type. Use union types for nullable values. Use generic types for collections. Define type aliases for complex or repeated signatures (e.g., a factory callable, a filter mapping). Avoid `any` / untyped containers. The type checker must pass with zero errors on every commit.
 
 ---
 
 ## P10 · Service Orchestration
 
-Services accept all dependencies via constructor — no hidden state:
-
-```python
-# Production code
-class AnalysisService:
-    def __init__(
-        self,
-        repository: Repository,
-        evaluator: EvaluationService,
-    ):
-        self._repository = repository
-        self._evaluator = evaluator
-
-# Test code — inject mocks
-service = AnalysisService(
-    repository=mock_repository,
-    evaluator=mock_evaluator,
-)
-```
+Services accept all dependencies via constructor — no hidden state.
+
+A service class receives every collaborator (repositories, other services, external clients) through its constructor. The constructor stores them as private fields. No service creates its own dependencies internally. This makes the dependency graph explicit and enables test doubles to be injected without patching or monkey-patching.
 
 ---
 
 ## P11 · Config Isolation
 
-Centralized, environment-based configuration with startup validation:
-
-```python
-@dataclass
-class Config:
-    database_url: str
-    debug: bool = False
-    max_workers: int = 4
+Centralized, environment-based configuration with startup validation.
 
-    @classmethod
-    def from_env(cls) -> "Config":
-        return cls(
-            database_url=os.environ["DATABASE_URL"],
-            debug=os.environ.get("DEBUG", "0") == "1",
-            max_workers=int(os.environ.get("MAX_WORKERS", "4")),
-        )
-```
+Define a configuration class with typed fields and default values. A class method reads all values from environment variables at startup, parsing them into the correct types. If a required variable is missing, startup fails immediately with a clear error. No other code reads environment variables directly — all access goes through the configuration instance.
 
 **Key rules:**
 - All config read from environment at startup
-- No scattered `os.environ` calls inside business logic
+- No scattered environment variable calls inside business logic
 - Test config overrides controlled via fixtures
 
 ---