@elevasis/sdk 0.5.12 → 0.5.13

package/reference/framework/agent.mdx

@@ -1,151 +1,168 @@
----
-title: Agent System
-description: CLAUDE.md drives all agent behavior -- project instructions, slash commands, memory-based developer profile, and three-tier adaptive guidance
-loadWhen: "Configuring agent behavior or capabilities"
----
-
-The agent system is the set of files that shape how Claude Code behaves in your SDK project. It consists of four parts: `CLAUDE.md` (the instruction file), slash commands (structured task entry points), the developer profile stored in `memory/profile/`, and the adaptive guidance rules that translate profile data into concrete agent behavior.
-
-Nothing here requires configuration. The agent reads these files at session start and adapts automatically.
-
-## CLAUDE.md
-
-`CLAUDE.md` is the project instruction file for Claude Code. It is read at the start of every session and governs all agent behavior. In an Elevasis SDK project, it is generated by `elevasis-sdk init` and lives at the project root.
-
-The file is instruction-driven by design. Non-technical developers should never need to edit it. When the agent learns a new rule worth preserving -- such as an error pattern that recurs three times -- it promotes that rule into `CLAUDE.md` automatically.
-
-### Sections
-
-The generated `CLAUDE.md` contains these sections:
-
-- **Session Initialization** -- Checks the `<!-- initialized: false -->` auto-init flag; if false, runs `/meta init` automatically. Otherwise reads `memory/profile/skills.md` for adaptive behavior, reads `memory/index.md` for project context, checks if the template version is current, and suggests `/tutorial` for users with no Platform Navigation experience.
-- **Identity** -- Project orientation: what an Elevasis SDK project is, the developer's role, and how to adapt to non-technical users.
-- **Navigation** -- A table mapping concepts to file paths with load conditions (when to load each file). Includes SDK reference docs, credential model, error history, `docs/project-map.mdx`, and `docs/priorities.mdx`.
-- **Rules** -- Points to auto-loaded rule files in `.claude/rules/`. SDK patterns load automatically; project-specific patterns live in `workspace-patterns.md`. Includes error handling protocol.
-- **Interaction Guidance** -- Per-dimension behavior rules derived from `memory/profile/skills.md`. Covers vocabulary, code completeness, explanation depth, and growth logging.
-- **Commands** -- Table of the 4 slash commands (`/meta`, `/docs`, `/work`, `/tutorial`) with one-line purpose descriptions.
-- **Skills** -- Auto-trigger conditions for the `creds` skill.
-- **Maintaining Memory** -- Hierarchical structure, pruning rules, and what belongs in memory vs. `docs/` vs. `.claude/rules/`.
-
-### Session Initialization
-
-At the start of every session the agent runs these steps silently before responding:
-
-0. Check the `<!-- initialized: ... -->` flag at the top of `CLAUDE.md`. If `false`, run the `/meta init` flow automatically. If `true`, proceed with steps below.
-1. Read `.claude/memory/profile/skills.md` -- adapt all responses to the user's assessed skill levels (see Interaction Guidance below).
-2. Read `.claude/memory/index.md` if it exists -- drill into relevant topic files as needed, balancing context relevance against token usage.
-3. Check the installed `@elevasis/sdk` template version against `templateVersion` in `elevasis.config.ts`. If the SDK has a newer version, notify the user and suggest running `/meta fix`.
-4. If `.claude/memory/` does not exist, suggest running `/meta init` to set up the project.
-5. If the user's Platform Navigation level is none (from skills.md) and `.claude/memory/tutorial-progress.md` does not exist, suggest `/tutorial`.
-
-## Slash Commands
-
-Slash commands are short Markdown instruction files in `.claude/commands/`. When you type `/command-name` in a Claude Code session, the agent reads the corresponding file and follows its instructions.
-
-Four commands and one skill are scaffolded by `elevasis-sdk init` and committed to version control so collaborators get the same experience:
-
-| Command | File | Purpose |
-| --- | --- | --- |
-| `/meta` | `meta.md` | Project lifecycle -- init, status, fix (incl. docs verification), deploy, health |
-| `/docs` | `docs.md` | Browse, create, and verify permanent documentation |
-| `/work` | `work.md` | Task tracking -- list, create, save, resume, complete |
-| `/tutorial` | `tutorial.md` | Progressive learning path -- 3 tracks, menu-driven |
-
-The `/creds` skill (`.claude/skills/creds/SKILL.md`) is also scaffolded. It auto-triggers when the agent detects credential-related context and manages credential storage and retrieval.
-
-### `/meta` Command
-
-The `/meta` command namespace manages the full project lifecycle. It has five operations:
-
-- **`/meta init`** -- First-run guided setup. Runs after `elevasis-sdk init` to install dependencies, configure `.env`, run the competency assessment onboarding flow, seed `memory/profile/`, verify the project, and optionally do a first deploy.
-- **`/meta`** (no arguments) -- Project health status. Shows current template version, SDK version, profile summary, a quick drift check, and last deployment status.
-- **`/meta fix`** -- SDK upgrade check and drift repair. Step 0 offers to run `pnpm update @elevasis/sdk` and merge template changes. Steps 1-8 repair drift: missing managed files, gitignore entries, CLAUDE.md sections, memory structure, doc cross-references, settings, rules health, and project map freshness.
-- **`/meta deploy`** -- Full 9-step deploy pipeline: validate, type-check, verify docs, commit, deploy (auto-regenerates `docs/project-map.mdx`), verify platform, update deployment state, and optionally push.
-- **`/meta health`** -- Execution debugging and resource status; shows recent executions, analyzes failures, and checks environment connectivity.
-
-### `/docs` Command
-
-The `/docs` command manages the permanent `docs/` tree -- everything except `docs/in-progress/` (owned by `/work`) and auto-generated files (`project-map.mdx`, `resource-map.mdx`). Three operations:
-
-- **`/docs`** (no arguments) -- Browse. Scans `docs/` recursively and displays a numbered list of user-maintained docs with auto-generated files shown separately as read-only. Pick a number to read and discuss, or say "create" or "verify."
-- **`/docs create [description]`** -- Interview-driven reference doc creation. If the doc is about a specific resource, the agent scans `src/` and pre-populates from code (config, schemas, step names, platform tools). Scaffolds sections appropriate to the doc type (resource guide, integration guide, architecture notes, process doc, or general reference).
-- **`/docs verify [file?]`** -- Interactive standalone version of `/meta fix` step 5. Cross-references resource IDs, schema fields, and platform tools in docs against `src/`. Shows a summary, then guides fixes interactively. Can be scoped to a single file.
-
-### `/work` Command
-
-The `/work` command manages in-progress task tracking across sessions. It uses `docs/in-progress/` for task documents with standardized frontmatter (`status: planned | in-progress | complete`). Operations:
-
-- **`/work`** (no arguments) -- Numbered list sorted by status (`in-progress` first) with last-saved date and current step. Pick by number to auto-resume.
-- **`/work create`** -- Guided interview (3-4 questions) to create a task document with intelligent placement in `docs/in-progress/`.
-- **`/work save`** -- Comprehensive snapshot: progress markers, files modified table, key docs to read on resume, and a "To continue" prompt. Proactively suggested before context pressure builds.
-- **`/work resume [<name>]`** -- Load a task by number, keyword, or auto-detect. No file paths required.
-- **`/work complete`** -- Seven-step pipeline: validate readiness, clean doc, determine destination in `docs/`, confirm with user, move, verify.
-
-### `/tutorial` Command
-
-The `/tutorial` command shows a track menu on every invocation and runs a progressive learning path adapted to the user's skill profile. Three tracks: Orchestration Concepts (7 lessons), Examples & Advanced Modules (9 standalone modules), and Meta-Framework (5 lessons). Two skill dimensions tracked: `automation` (none / low-code / custom) and `platformNavigation` (none / oriented / comfortable).
-
-## Developer Profile
-
-The developer profile is stored in `.claude/memory/profile/` as a set of markdown files. It is gitignored -- personal to each developer, not shared with collaborators. Profile data lives in the memory system alongside error patterns, deployment state, and decisions.
-
-### Onboarding Flow
-
-Profile data is created during `/meta init`. The command runs a 6-question assessment and writes the responses to `memory/profile/`:
-
-- **Identity & Goals (3 questions):** What the business does, what to automate, which tools are already in use.
-- **Competency (2 questions):** Command Center familiarity (maps to `platformNavigation`), automation tool familiarity (maps to `automation`). Two additional dimensions (`apiIntegration`, `domainExpertise`) are inferred from these answers.
-- **Communication (1 question):** Step-by-step explanations vs. concise answers.
-
-### Profile Structure
-
-```
-.claude/memory/profile/
-├── index.md          # Profile summary with links to sub-files
-├── identity.md       # Organization, industry, goals, integrations
-├── skills.md         # Skill dimensions (platformNavigation, apiIntegration, automation, domainExpertise)
-└── preferences.md    # Verbosity, guidance style, interaction patterns
-```
-
-`identity.md` records the organization name, industry, size, project goals, and known tool integrations. `skills.md` stores four skill dimensions as structured values (`platformNavigation`, `apiIntegration`, `automation`, `domainExpertise`) along with a Growth Log table. See [Interaction Guidance](../developer/interaction-guidance.mdx) for the full set of per-dimension adaptation rules. `preferences.md` stores verbosity (`detailed / concise`) and proactive guidance preference.
-
-### Auto-Update Triggers
-
-The agent updates `memory/profile/` files when it observes:
-
-- The user successfully completes an advanced task (level upgrade candidate in `skills.md`)
-- The user mentions new tools or integrations not in `identity.md`
-- The user explicitly asks to change preferences
-
-The agent does not prompt for confirmation on minor updates. Major changes (level upgrades) are surfaced to the user before writing.
-
-## Rules System
-
-Six rule files are scaffolded in `.claude/rules/`. Rule files are auto-injected by Claude Code when their path patterns match the current file being edited -- no manual loading needed.
-
-| File | Type | When Injected | What It Covers |
-| --- | --- | --- | --- |
-| `sdk-patterns.md` | MANAGED | Any file in `src/` | SDK imports, source structure, runtime, typed adapter patterns |
-| `docs-authoring.md` | MANAGED | Any `.mdx` file in `docs/` | MDX escaping, frontmatter requirements, doc structure |
-| `memory-conventions.md` | MANAGED | Any file in `.claude/memory/` | What belongs in memory, structure, pruning |
-| `project-map.md` | MANAGED | `docs/project-map.mdx` | Auto-generated map conventions, do not edit manually |
-| `task-tracking.md` | MANAGED | Any file in `docs/in-progress/` | `/work` command, task doc format, status values |
-| `workspace-patterns.md` | INIT_ONLY | Any file in the project | Project-specific patterns (starts empty, grows via error promotion) |
-
-MANAGED rules are updated by `elevasis-sdk update` when the SDK ships a new version. `workspace-patterns.md` is INIT_ONLY -- it belongs to the project and is never overwritten. When an error recurs 3+ times, the agent promotes a fix into this file so future sessions learn from past mistakes.
-
-## Interaction Guidance
-
-The `CLAUDE.md` Interaction Guidance section translates skill dimensions from `memory/profile/skills.md` into concrete behavior rules. Rather than fixed tiers, the agent adapts per dimension:
-
-- **Match vocabulary to level.** Avoid jargon for beginners; be precise for experts. Define technical terms in parentheses the first time they appear.
-- **Show complete code for lower-programming users.** Users below intermediate programming level get full working files, never fragments they can't place.
-- **Explain "why" before "how" for users new to automation.** Users comfortable with code get SDK-specific pattern focus instead.
-- **Leverage domain expertise.** If the user knows sales but not code, ask for business process descriptions and translate.
-- **Log observed growth.** When the agent observes the user doing something they previously needed help with, add an entry to `skills.md` Growth Log.
-
-For detailed per-dimension adaptation rules, read `reference/developer/interaction-guidance.mdx`.
-
----
-
-**Last Updated:** 2026-03-03
+---
+title: Agent System
+description: CLAUDE.md drives all agent behavior -- project instructions, slash commands, memory-based developer profile, and three-tier adaptive guidance
+loadWhen: "Configuring agent behavior or capabilities"
+---
+
+The agent system is the set of files that shape how Claude Code behaves in your SDK project. It consists of four parts: `CLAUDE.md` (the instruction file), slash commands (structured task entry points), the developer profile stored in `memory/profile/`, and the adaptive guidance rules that translate profile data into concrete agent behavior.
+
+Nothing here requires configuration. The agent reads these files at session start and adapts automatically.
+
+## CLAUDE.md
+
+`CLAUDE.md` is the project instruction file for Claude Code. It is read at the start of every session and governs all agent behavior. In an Elevasis SDK project, it is generated by `elevasis-sdk init` and lives at the project root.
+
+The file is instruction-driven by design. Non-technical developers should never need to edit it. When the agent learns a new rule worth preserving -- such as an error pattern that recurs three times -- it promotes that rule into `CLAUDE.md` automatically.
+
+### Sections
+
+The generated `CLAUDE.md` contains these sections:
+
+- **Session Initialization** -- Checks the `<!-- initialized: false -->` auto-init flag; if false, runs `/meta init` automatically. Otherwise reads `memory/profile/skills.md` for adaptive behavior, reads `memory/index.md` for project context, checks if the template version is current, and suggests `/tutorial` for users with no Platform Navigation experience.
+- **Identity** -- Project orientation: what an Elevasis SDK project is, the developer's role, and how to adapt to non-technical users.
+- **Navigation** -- A table mapping concepts to file paths with load conditions (when to load each file). Includes SDK reference docs, credential model, error history, `docs/project-map.mdx`, and `docs/priorities.mdx`.
+- **Rules** -- Points to auto-loaded rule files in `.claude/rules/`. SDK patterns load automatically; project-specific patterns live in `workspace-patterns.md`. Includes error handling protocol.
+- **Interaction Guidance** -- Per-dimension behavior rules derived from `memory/profile/skills.md`. Covers vocabulary, code completeness, explanation depth, and growth logging.
+- **Commands** -- Table of the 4 slash commands (`/meta`, `/docs`, `/work`, `/tutorial`) with one-line purpose descriptions.
+- **Skills** -- Auto-trigger conditions for the `creds` skill.
+- **Maintaining Memory** -- Hierarchical structure, pruning rules, and what belongs in memory vs. `docs/` vs. `.claude/rules/`.
+
+### Session Initialization
+
+At the start of every session the agent runs these steps silently before responding:
+
+0. Check the `<!-- initialized: ... -->` flag at the top of `CLAUDE.md`. If `false`, run the `/meta init` flow automatically. If `true`, proceed with steps below.
+1. Read `.claude/memory/profile/skills.md` -- adapt all responses to the user's assessed skill levels (see Interaction Guidance below).
+2. Read `.claude/memory/index.md` if it exists -- drill into relevant topic files as needed, balancing context relevance against token usage.
+3. Check the installed `@elevasis/sdk` template version against `templateVersion` in `elevasis.config.ts`. If the SDK has a newer version, notify the user and suggest running `/meta fix`.
+4. If `.claude/memory/` does not exist, suggest running `/meta init` to set up the project.
+5. If the user's Platform Navigation level is none (from skills.md) and `.claude/memory/tutorial-progress.md` does not exist, suggest `/tutorial`.
+
+## Slash Commands
+
+Slash commands are short Markdown instruction files in `.claude/commands/`. When you type `/command-name` in a Claude Code session, the agent reads the corresponding file and follows its instructions.
+
+Four commands and one skill are scaffolded by `elevasis-sdk init` and committed to version control so collaborators get the same experience:
+
+| Command     | File          | Purpose                                                                          |
+| ----------- | ------------- | -------------------------------------------------------------------------------- |
+| `/meta`     | `meta.md`     | Project lifecycle -- init, status, fix (incl. docs verification), deploy, health |
+| `/docs`     | `docs.md`     | Browse, create, and verify permanent documentation                               |
+| `/work`     | `work.md`     | Task tracking -- list, create, save, resume, complete                            |
+| `/tutorial` | `tutorial.md` | Progressive learning path -- 3 tracks, menu-driven                               |
+
+The `/creds` skill (`.claude/skills/creds/SKILL.md`) is also scaffolded. It auto-triggers when the agent detects credential-related context and manages credential storage and retrieval.
+
+### `/meta` Command
+
+The `/meta` command namespace manages the full project lifecycle. It has five operations:
+
+- **`/meta init`** -- First-run guided setup. Runs after `elevasis-sdk init` to install dependencies, configure `.env`, run the competency assessment onboarding flow, seed `memory/profile/`, verify the project, and optionally do a first deploy.
+- **`/meta`** (no arguments) -- Project health status. Shows current template version, SDK version, profile summary, a quick drift check, and last deployment status.
+- **`/meta fix`** -- SDK upgrade check and drift repair. Step 0 offers to run `pnpm update @elevasis/sdk` and merge template changes. Steps 1-8 repair drift: missing managed files, gitignore entries, CLAUDE.md sections, memory structure, doc cross-references, settings, rules health, and project map freshness.
+- **`/meta deploy`** -- Full 9-step deploy pipeline: validate, type-check, verify docs, commit, deploy (auto-regenerates `docs/project-map.mdx`), verify platform, update deployment state, and optionally push.
+- **`/meta health`** -- Execution debugging and resource status; shows recent executions, analyzes failures, and checks environment connectivity.
+
+### `/docs` Command
+
+The `/docs` command manages the permanent `docs/` tree -- everything except `docs/in-progress/` (owned by `/work`) and auto-generated files (`project-map.mdx`, `resource-map.mdx`). Three operations:
+
+- **`/docs`** (no arguments) -- Browse. Scans `docs/` recursively and displays a numbered list of user-maintained docs with auto-generated files shown separately as read-only. Pick a number to read and discuss, or say "create" or "verify."
+- **`/docs create [description]`** -- Interview-driven reference doc creation. If the doc is about a specific resource, the agent scans `src/` and pre-populates from code (config, schemas, step names, platform tools). Scaffolds sections appropriate to the doc type (resource guide, integration guide, architecture notes, process doc, or general reference).
+- **`/docs verify [file?]`** -- Interactive standalone version of `/meta fix` step 5. Cross-references resource IDs, schema fields, and platform tools in docs against `src/`. Shows a summary, then guides fixes interactively. Can be scoped to a single file.
+
+### `/work` Command
+
+The `/work` command manages in-progress task tracking across sessions. It uses `docs/in-progress/` for task documents with standardized frontmatter (`status: planned | in-progress | complete`). Operations:
+
+- **`/work`** (no arguments) -- Numbered list sorted by status (`in-progress` first) with last-saved date and current step. Pick by number to auto-resume.
+- **`/work create`** -- Guided interview (5 questions) covering objective, acceptance criteria, relation to existing work, investigation needed, and placement. New docs start with `status: planned`. Placement is determined intelligently: related directory, new directory for multi-file tasks, flat file for small tasks.
+- **`/work save`** -- Comprehensive snapshot: progress markers, files modified table, key docs to read on resume, and a copy-pasteable "To continue" prompt. Proactively suggested before context pressure builds.
+- **`/work resume [<name>]`** -- Load a task by number, keyword, or auto-detect. Loads key docs in parallel and verifies referenced files exist. No file paths required.
+- **`/work complete`** -- Seven-step pipeline: resolve target, validate readiness, clean doc (strip resume context, remove progress markers, target 200-400 lines), determine destination in `docs/`, confirm with user, move, verify.
+
+When all plan steps for a task are marked COMPLETE and the user appears to be moving on, the agent proactively suggests running `/work complete`.
+
+**Directory conventions for `docs/in-progress/`:**
+
+```
+docs/in-progress/
+├── crm-integration/
+│   ├── index.mdx          # Main task doc
+│   └── attio-schema.mdx   # Supporting analysis
+├── email-templates.mdx    # Small standalone task
+└── ui-dashboard/
+    ├── index.mdx          # Main task doc
+    └── component-list.mdx # Supporting analysis
+```
+
+The numbered list is derived from scanning this directory. `index.mdx` is treated as the primary task doc for a directory. On complete, destination in `docs/` is determined by scanning for related existing directories.
+
+### `/tutorial` Command
+
+The `/tutorial` command shows a track menu on every invocation and runs a progressive learning path adapted to the user's skill profile. Three tracks: Orchestration Concepts (7 lessons), Examples & Advanced Modules (9 standalone modules), and Meta-Framework (5 lessons). Two skill dimensions tracked: `automation` (none / low-code / custom) and `platformNavigation` (none / oriented / comfortable).
+
+## Developer Profile
+
+The developer profile is stored in `.claude/memory/profile/` as a set of markdown files. It is gitignored -- personal to each developer, not shared with collaborators. Profile data lives in the memory system alongside error patterns, deployment state, and decisions.
+
+### Onboarding Flow
+
+Profile data is created during `/meta init`. The command runs a 6-question assessment and writes the responses to `memory/profile/`:
+
+- **Identity & Goals (3 questions):** What the business does, what to automate, which tools are already in use.
+- **Competency (2 questions):** Command Center familiarity (maps to `platformNavigation`), automation tool familiarity (maps to `automation`). Two additional dimensions (`apiIntegration`, `domainExpertise`) are inferred from these answers.
+- **Communication (1 question):** Step-by-step explanations vs. concise answers.
+
+### Profile Structure
+
+```
+.claude/memory/profile/
+├── index.md          # Profile summary with links to sub-files
+├── identity.md       # Organization, industry, goals, integrations
+├── skills.md         # Skill dimensions (platformNavigation, apiIntegration, automation, domainExpertise)
+└── preferences.md    # Verbosity, guidance style, interaction patterns
+```
+
+`identity.md` records the organization name, industry, size, project goals, and known tool integrations. `skills.md` stores four skill dimensions as structured values (`platformNavigation`, `apiIntegration`, `automation`, `domainExpertise`) along with a Growth Log table. See [Interaction Guidance](interaction-guidance.mdx) for the full set of per-dimension adaptation rules. `preferences.md` stores verbosity (`detailed / concise`) and proactive guidance preference.
+
+### Auto-Update Triggers
+
+The agent updates `memory/profile/` files when it observes:
+
+- The user successfully completes an advanced task (level upgrade candidate in `skills.md`)
+- The user mentions new tools or integrations not in `identity.md`
+- The user explicitly asks to change preferences
+
+The agent does not prompt for confirmation on minor updates. Major changes (level upgrades) are surfaced to the user before writing.
+
+## Rules System
+
+Six rule files are scaffolded in `.claude/rules/`. Rule files are auto-injected by Claude Code when their path patterns match the current file being edited -- no manual loading needed.
+
+| File                    | Type      | When Injected                   | What It Covers                                                      |
+| ----------------------- | --------- | ------------------------------- | ------------------------------------------------------------------- |
+| `sdk-patterns.md`       | MANAGED   | Any file in `src/`              | SDK imports, source structure, runtime, typed adapter patterns      |
+| `docs-authoring.md`     | MANAGED   | Any `.mdx` file in `docs/`      | MDX escaping, frontmatter requirements, doc structure               |
+| `memory-conventions.md` | MANAGED   | Any file in `.claude/memory/`   | What belongs in memory, structure, pruning                          |
+| `project-map.md`        | MANAGED   | `docs/project-map.mdx`          | Auto-generated map conventions, do not edit manually                |
+| `task-tracking.md`      | MANAGED   | Any file in `docs/in-progress/` | `/work` command, task doc format, status values                     |
+| `workspace-patterns.md` | INIT_ONLY | Any file in the project         | Project-specific patterns (starts empty, grows via error promotion) |
+
+MANAGED rules are updated by `elevasis-sdk update` when the SDK ships a new version. `workspace-patterns.md` is INIT_ONLY -- it belongs to the project and is never overwritten. When an error recurs 3+ times, the agent promotes a fix into this file so future sessions learn from past mistakes.
+
+## Interaction Guidance
+
+The `CLAUDE.md` Interaction Guidance section translates skill dimensions from `memory/profile/skills.md` into concrete behavior rules. Rather than fixed tiers, the agent adapts per dimension:
+
+- **Match vocabulary to level.** Avoid jargon for beginners; be precise for experts. Define technical terms in parentheses the first time they appear.
+- **Show complete code for lower-programming users.** Users below intermediate programming level get full working files, never fragments they can't place.
+- **Explain "why" before "how" for users new to automation.** Users comfortable with code get SDK-specific pattern focus instead.
+- **Leverage domain expertise.** If the user knows sales but not code, ask for business process descriptions and translate.
+- **Log observed growth.** When the agent observes the user doing something they previously needed help with, add an entry to `skills.md` Growth Log.
+
+For detailed per-dimension adaptation rules, read `reference/developer/interaction-guidance.mdx`.
+
+---
+
+**Last Updated:** 2026-03-03