Engram Architecture Guardrails
Architecture guardrails for Engram across local store, cloud sync, dashboard, and plugins.
Evidence: The skill itself only provides architectural guidelines, no permissions, data flow, or external effects; hence trust risk is low. Repository-level SECURITY.md provides vulnerability reporting process and dependency vetting policies, but the skill lacks explicit confirmation mechanisms or rollback practices. Deduction: The skill is purely advisory with no user confirmation or isolation details; experimental cloud features may introduce unknown risks. Award 15, above 12 but below 25.
Evidence: The skill has clear steps (when to use, core guardrails, decision rules, validation), aligning with repository design. But no executable tests or explicit failure-feedback for abnormal inputs. Deduction: Static review cannot verify key paths; no troubleshooting guidance in skill. Per static calibration, award 5.
Evidence: The skill defines trigger conditions and scenarios (adding subsystems, moving responsibilities, changing sync flow) and provides decision rules (e.g., local-only -> internal/store). Deduction: No explicit non-fit boundaries, no environment adaptation evidence (Chinese support, network reachability). So award 10.
Evidence: Skill file is well-structured with sections; repository has README, LICENSE (MIT), SECURITY.md, and CI workflows. Deduction: Skill has no versioning or changelog, unclear maintenance ownership, limited cross-referencing. Award 10.
Evidence: Skill content matches repository functionality (local SQLite as source of truth, cloud replication), guiding developers to follow architecture rules. Deduction: Static review cannot verify direct usability; skill is advisory, requiring manual application. Award 5.
Evidence: Repository has CI workflows (unit-tests, e2e-tests) and go.mod indicating tests; but no specific tests for this skill. Deduction: Static review cannot reproduce tests; cannot corroborate skill impact. Award 5.
- This skill is advisory only; it executes nothing, but note that experimental cloud features may carry unvetted security risks.
- The skill does not define non-fit scenarios, risking misapplication. Recommend adding clear boundaries and anti-patterns.
- Cloud integration relies on Docker and external services, potentially unsuitable for mainland-China networks; be cautious.
- Static review cannot verify effectiveness; test in real environments before adoption.
What does this skill do, and when should you use it?
This skill defines the architectural boundaries and decision rules for the Engram codebase. It specifies that local SQLite is the source of truth, cloud is replication/shared access, and plugin layers should be thin. It provides a clear mapping of where different concerns belong (e.g., store, cloudstore, cloudserver, dashboard, autosync) and mandates regression tests for boundary changes. It is intended to be used by AI coding agents when modifying Engram's architecture to maintain consistency and avoid coupling.
The skill reads the SKILL.md and README context to understand Engram's architecture. It provides guardrails and decision rules for placing new features or subsystems. It does not execute any code but serves as a reference guide for the AI agent during code modifications. It outputs architectural rules and validation requirements to ensure compliance with local-first design.
- When adding a new subsystem or major package to Engram, use this skill to decide boundaries and ownership.
- When moving responsibilities between local store, cloud, dashboard, or plugins, use this skill to maintain source-of-truth rules.
- When changing sync flow or persistence boundaries, use this skill to test both push and pull paths.
- When adding a new plugin or adapter, use this skill to keep layers thin and core logic in Go packages.
- When implementing dashboard or cloud features, use this skill to ensure they fit the local-first model.
What are this skill's strengths and limitations?
- Provides clear, actionable architecture guidelines reducing ambiguity.
- Enforces local-first model ensuring data ownership clarity.
- Requires regression tests and validation for boundary changes, improving reliability.
- Directly maps to Engram's package structure, making it easy to apply.
- Specific to Engram engineering, not general-purpose.
- Does not include actual test suite implementation; only mandates manual addition.
- Lacks mention of platform-specific validation like Windows or Linux.
- Relies on developers following rules without automated enforcement.
How do you install this skill?
The skill is located at skills/architecture-guardrails/ in the monorepo. For Claude Code, copy the folder to .claude/skills/ or use the skill marketplace if available. As part of a monorepo, it may already be present in the repository.
How do you use this skill?
Trigger when the AI coding agent is editing the Engram codebase and a change affects system boundaries, ownership, state flow, or cross-package responsibilities. For example, when adding a new subsystem or moving responsibilities, consult the guardrails and decision rules to guide the changes.