@elevasis/sdk 1.44.3 → 1.46.0

package/reference/sdk/framework/index.mdx

@@ -1,12 +1,12 @@
 ---
 title: Development Framework
-description: The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, template versioning, and resource documentation
+description: The template ships an agent operating environment alongside your code -- always-loaded rules, slash-command skills, a two-track tutorial, and a small gitignored memory surface
 loadWhen: "Understanding the agent framework structure"
 ---
 
-Your Elevasis SDK project ships with more than code. It builds a development environment designed around Claude Code as the primary interface. Most external SDK developers are non-technical -- they write workflows through conversation, not by reading API docs. The framework gives the agent everything it needs to guide those users effectively from the first session onward.
+Your Elevasis SDK project ships with more than code. It builds an agent operating environment around Claude Code as the primary interface. Most external SDK developers are non-technical -- they write workflows through conversation, not by reading API docs. The framework gives the agent everything it needs to guide those users effectively from the first session onward.
 
-The framework lives entirely in `.claude/`. It is never deployed and never touches the `docs/` directory, which ships to the platform.
+The framework lives entirely in `.claude/`. It is never deployed and never bundled into `operations/dist/`.
 
 ## What Ships With Your Project
 
@@ -14,98 +14,79 @@ Your Elevasis SDK project includes the following agent infrastructure alongside
 
 ```
 .claude/
-├── settings.json               # Hook registrations (PostToolUse, PostToolUseFailure)
+├── Overview.md          # Routing map: skills, rules, hooks, project structure, stack, commands
+├── settings.json         # Hook registrations (PostToolUse, PostToolUseFailure) + statusline command
 ├── hooks/
-│   ├── post-edit-validate.mjs    # Formatting/type-check hook (after Write/Edit/MultiEdit)
-│   └── tool-failure-recovery.mjs # Error recovery hook (after Bash failures)
+│   ├── post-edit-validate.mjs        # Formatting/type-check hook (after Write/Edit/MultiEdit)
+│   ├── scaffold-registry-reminder.mjs # Reminds about generated-file regeneration
+│   └── tool-failure-recovery.mjs     # Error recovery hook (after Bash failures)
 ├── skills/
-│   ├── work/SKILL.md           # Task tracking across sessions
-│   ├── elevasis/SKILL.md       # SDK operations (check, deploy, exec)
-│   ├── deploy/skill.md         # Deploy pipeline
-│   ├── setup/SKILL.md          # First-time project setup
-│   ├── status/SKILL.md         # Project health check
-│   └── ...                     # Additional skills (dsp, continue, project, sync, explore, save)
-├── scripts/
-│   └── statusline-command.js   # Status line command
+│   ├── client/SKILL.md         # Client portfolio management
+│   ├── deploy/SKILL.md         # Test, build, commit, push pipeline
+│   ├── dsp/SKILL.md            # Parallel agent dispatch
+│   ├── elevasis/SKILL.md       # SDK operations -- check, deploy, exec, describe, logs, creds
+│   ├── explore/SKILL.md        # Codebase exploration anchored to docs
+│   ├── git-sync/SKILL.md       # Pull latest, install when the baseline moved, baseline-verify
+│   ├── om/SKILL.md             # Organization Model read/codify/toggle ceremony
+│   ├── project/SKILL.md        # Project/milestone/task/note lifecycle via elevasis-sdk project:*
+│   ├── run-ui/SKILL.md         # Start the Vite dev server on port 4300
+│   ├── save/SKILL.md           # Conversation fanout -- docs, task resume context, notes
+│   ├── setup/SKILL.md          # First-time project bootstrap, then hands off to /om
+│   ├── status/SKILL.md         # Quick project health check
+│   ├── submit-request/SKILL.md # Submit a structured request to the Elevasis platform
+│   ├── sync/SKILL.md           # Fresh reinstall and cache reset
+│   └── tutorial/SKILL.md       # Two-track onboarding (vibe-coder / technical)
+├── registries/            # Scaffold, skill-coverage, and knowledge registry data
 └── rules/
-    ├── sdk-patterns.md         # SDK patterns (auto-loaded for src/ files)
-    ├── docs-authoring.md       # MDX conventions (auto-loaded for docs/ files)
-    ├── task-tracking.md        # Task tracking conventions (auto-loaded)
-    ├── platform.md             # Platform tool patterns
-    ├── error-handling.md       # Error handling patterns
-    └── workspace-patterns.md   # Project-specific patterns (grows over time)
+    ├── agent-start-here.md   # Session bootstrap pointer, task-class routing, boundary resolution
+    ├── vibe.md                # Ambient intent classifier (always on in external projects)
+    └── ...                    # Thin pointers to the bundled rule bodies (see below)
 ```
 
-The `memory/` directory is gitignored -- it is personal to each developer and not shared with collaborators. Everything else in `.claude/` is committed.
+`.claude/Overview.md` is the authoritative routing map for this directory -- read it first. It is template-owned and replaced on every sync; project-specific facts live in `CLAUDE.md` (never overwritten) and tenant operational quirks live in `OPERATIONS.md` (also never overwritten).
 
-CLAUDE.md is scaffolded with an `<!-- initialized: false -->` HTML comment at the very top. When the agent reads this flag on session start and finds it false, it automatically runs the `/meta init` flow -- no slash command knowledge required from the user. After initialization completes the agent changes the flag to `<!-- initialized: true -->`, so subsequent sessions proceed normally.
+The rule _bodies_ referenced by `.claude/rules/*.md` ship with the installed `@elevasis/sdk` package, not the git-tracked template: `operations/node_modules/@elevasis/sdk/reference/rules/`. The local `.claude/rules/` files are short pointers with `paths:` frontmatter that Claude Code auto-loads; the full content lives in the installed package and updates whenever you bump `@elevasis/sdk`.
+
+`.claude/memory/` is not part of the scaffold -- it does not ship with the template and is gitignored. It is created at runtime the first time a skill needs to persist state (for example, `/tutorial` creates `.claude/memory/profile.md` on first invocation). It is personal to each developer and not shared with collaborators.
 
 ## Why It Works This Way
 
 The agent needs three things to guide a non-technical developer well:
 
-- **Who the user is** -- their TypeScript experience, automation background, and project goals, stored in `.claude/memory/profile/` as markdown files and created during `/meta init`
-- **What has happened in this project** -- deployment state, credentials, errors encountered, and architectural decisions, stored in `.claude/memory/` and loaded on demand
-- **How to behave** -- adaptive guidance rules in `CLAUDE.md` that translate experience levels into concrete behaviors: complete code examples for beginners, concise fixes for advanced users
-
-The agent reads `memory/index.md` at session start and drills into `memory/profile/skills.md` for adaptive behavior. It adjusts its tone, explanation depth, and proactivity based on what it finds. This happens silently -- the developer sees a helpful response, not a loading message.
+- **Session orientation** -- `agent-start-here.md` is the canonical first-read: it establishes that project context (milestones, tasks, resume notes) is DB-canonical through `elevasis-sdk project:*`, not files, and that a tenant's own `OPERATIONS.md` outranks generic guidance.
+- **What has happened in this project** -- deployment state and architectural facts live in `OPERATIONS.md` and `CONNECTIONS.md` (both tenant-owned, never overwritten by sync), plus whatever the agent has written to the gitignored `.claude/memory/`.
+- **How to behave** -- the ambient vibe layer (see [Agent System](agent.mdx)) classifies every natural-language message into an intent before the agent responds, and the `/tutorial` track choice in `.claude/memory/profile.md` shapes vocabulary and tone project-wide once set.
 
 ## The Framework Components
 
 ### Agent System
 
-The `CLAUDE.md` file drives all agent behavior. It contains the session initialization instructions, adaptive guidance tiers, memory maintenance rules, and slash command definitions. No hooks, no code enforcement -- everything is instruction-driven so non-technical users never need to configure anything.
-
-The `/meta` command manages the project lifecycle: `/meta init` for guided setup, `/meta fix` for SDK upgrades, drift repair, and documentation verification, `/meta deploy` for deployments, `/meta health` for debugging executions. `/docs` browses, creates, and verifies permanent documentation in `docs/`. `/work` tracks tasks across sessions, and `/tutorial` guides new developers through a menu-driven multi-track learning path. A `creds` skill auto-triggers when credential setup is needed.
-
-See [Agent System](agent.mdx) for CLAUDE.md sections, slash command reference, developer profile, and adaptive guidance tiers.
-
-### Memory System
-
-The `memory/` directory follows a hierarchical index tree pattern: a root `index.md` maps to topic files and subdirectories, each subdirectory has its own index. The agent reads only the root index at session start and drills into detail files on demand. The `memory/profile/` subdirectory is seeded by `/meta init` during guided setup; other topics are created by the agent as needed.
+`CLAUDE.md` is project-owned and carries identity and preferences only -- it deliberately has no session-bootstrap procedure, because `.claude/rules/agent-start-here.md` owns that. `.claude/Overview.md` is the template-owned routing map for skills, rules, hooks, project structure, stack, and commands.
 
-Topics include developer profile (identity, skills, preferences), deployment state, environment credentials, architectural decisions, and error patterns. Error tracking starts as a subdirectory because it naturally spans multiple categories. Other topics start as flat files and split when they outgrow a single document.
+The skill layer covers the full development loop: `/setup` for first-time bootstrap, `/om` for organization-model edits, `/project` for portfolio and task work, `/elevasis` for SDK operations, `/deploy` for the test-build-commit-push pipeline, `/git-sync` for pulling template updates, and more. There is no `/meta`, `/docs`, or `/work` skill in the current template.
 
-See [Memory System](memory.mdx) for architecture, error tracking format, scaling rules, and maintenance guidelines.
+See [Agent System](agent.mdx) for the full skill inventory, the ambient vibe layer, and the session-bootstrap sequence.
 
 ### Project Structure
 
-The scaffolded project separates concerns clearly: `operations/` for executable resources, `core/` for shared contracts and Organization Model configuration, `ui/` for the shell, `docs/` for platform documentation, and `.claude/` for agent infrastructure. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
-
-See [Project Structure](project-structure.mdx) for a file-by-file walkthrough of the scaffolded project.
-
-## Adaptive Guidance
-
-The agent adapts its communication based on four independent skill dimensions stored in `memory/profile/skills.md`:
-
-| Dimension           | Levels                        | Assessment                       |
-| ------------------- | ----------------------------- | -------------------------------- |
-| Platform Navigation | none / oriented / comfortable | Direct question                  |
-| API & Integration   | none / basic / proficient     | Inferred from automation + tools |
-| Automation Concepts | none / low-code / custom      | Direct question                  |
-| Domain Expertise    | high / low                    | Inferred from identity answers   |
-
-Each dimension has its own adaptation rules in the [Interaction Guidance](interaction-guidance.mdx) reference. A user who has deep Zapier experience (automation: low-code) but has never called an API directly (apiIntegration: none) will get credential walkthroughs every time while having automation concepts treated as familiar ground.
+The scaffolded project separates concerns clearly: `operations/` for executable resources, `core/` for shared contracts and Organization Model configuration, `ui/` for the shell, and `.claude/` for agent infrastructure. There is no top-level `docs/` directory in the current template -- documentation content is not part of the deploy path.
 
-`/tutorial` runs the assessment via a single gate question on first invocation: are you here to build automations by describing what you want, or are you a developer who edits code directly. The choice persists to `.claude/memory/profile.md` and shapes the agent's tone, vocabulary, and tool-call visibility for the entire project, not just inside `/tutorial`. Within the chosen track, lessons adapt further -- senior devs in the technical track can mark Section A items complete to skip them.
+See [Project Structure](project-structure.mdx) for a directory-by-directory walkthrough of the scaffolded project.
 
-See [Agent System](agent.mdx) for the full assessment question set, dimensional interaction rules, and communication principles.
+### Onboarding
 
-### Skills Auto-Update
+`/tutorial` forks into a vibe-coder track (8 lessons, zero technical vocabulary) or a technical track (19 lessons across 5 sections, code-first) on first invocation, asking a single gate question. The choice persists to `.claude/memory/profile.md` and shapes agent tone project-wide, not just inside `/tutorial`.
 
-The Growth Log in `memory/profile/skills.md` keeps approximately 20 recent entries. The agent adds an entry whenever it observes the user performing something they previously needed help with. When a consistent pattern of growth is observed -- typically after several independent successes -- the agent promotes the observation to a level change in the relevant dimension.
+See [Tutorial System](tutorial-system.mdx) for the full lesson breakdown, track persistence, and switching behavior.
 
 ---
 
 ## Documentation
 
-- [Project Structure](project-structure.mdx) - File-by-file walkthrough of every scaffolded file and its purpose
-- [Agent System](agent.mdx) - CLAUDE.md sections, slash commands, developer profile, and adaptive guidance tiers
-- [Memory System](memory.mdx) - Architecture, error tracking format, scaling rules, and maintenance guidelines
-- [Interaction Guidance](interaction-guidance.mdx) - Dimensional adaptation rules per skill axis with growth tracking protocol
-- [Tutorial System](tutorial-system.mdx) - Two-track onboarding (8 vibe-coder + 19 technical lessons), skill-adaptive lesson variants, and progress tracking
-- [Resource Documentation](resource-documentation.mdx) - Docs directory structure, frontmatter schema, size limits, deploy behavior, and /docs command reference
+- [Project Structure](project-structure.mdx) - Directory-by-directory walkthrough of the scaffolded project
+- [Agent System](agent.mdx) - Skill inventory, rules layer, ambient vibe classifier, and session bootstrap
+- [Tutorial System](tutorial-system.mdx) - Two-track onboarding (8 vibe-coder + 19 technical lessons), track persistence, and progress tracking
 
 ---
 
-**Last Updated:** 2026-03-06
+**Last Updated:** 2026-08-06