# Domain Model

> |

- **Type:** Skill
- **Install:** `agentstack add skill-techymt-claude-code-superpowers-domain-model`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TechyMT](https://agentstack.voostack.com/s/techymt)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TechyMT](https://github.com/TechyMT)
- **Source:** https://github.com/TechyMT/claude-code-superpowers/tree/main/skills/domain-model

## Install

```sh
agentstack add skill-techymt-claude-code-superpowers-domain-model
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Domain Model

## The pattern

A well-designed AI agent system separates three concerns: (1) **capability objects** — typed schemas declaring what the agent can do, with permission gates controlling access; (2) **runtime injection** — a context object passed to every capability invocation, carrying state, abort signals, and callbacks (so capabilities are independently testable, no global singletons); (3) **atomic state** — an immutable global store updated via reducer functions, so UI renders consistently and state transitions are traceable.

Claude Code names these: Tool (capability), ToolUseContext (injection), and AppState (state store). The other three concepts — Message, Task, and Command — complete the model: A **Tool** is a named capability with a typed input schema, a permission check, and an execution function. A **Message** is an immutable turn in the conversation — user input, assistant response, or system event. A **Task** is an optional background process that a tool can spawn. A **ToolUseContext** is the runtime environment injected into every tool call — it carries state, abort signals, callbacks, and configuration. **AppState** is the mutable global state store that the UI and tools read from and write to. A **Command** is a user-facing slash command that resolves to either a prompt template (injected into the conversation) or a local function.

Without understanding these six, you will model Claude Code incorrectly — treating it as a plain CLI instead of a React-driven state machine with a structured capability system.

## Why this matters

Claude Code must bridge an LLM (which communicates via structured JSON tool calls) with a local developer environment (file system, shell, git). The Tool abstraction provides a single contract: the LLM produces a `tool_name` + `input` JSON block, the runtime validates the input against a Zod schema, checks permissions, and calls `tool.call()`. The result is returned to the LLM as a tool result block.

The ToolUseContext solves a layering problem: tools need access to state, permissions, callbacks, and configuration without those being global singletons. Every tool call receives the full context, making tools independently testable and the dependency graph explicit.

AppState uses a Zustand-like pattern in a React TUI. State transitions happen atomically via `setAppState(prev => next)` — the same pattern as React's `setState`, but available outside React components via the context object.

## How to apply it

1. When writing a new Tool: use `buildTool({...})` from `src/Tool.ts` with a `get inputSchema()` getter. Define your Zod schema first — it drives the LLM's JSON schema, the validation, and the TypeScript type. Return `{ data: ... }` from `call()`.
2. When writing a new Command: define a `PromptCommand` (for prompt injection) or `LocalCommand` (for local execution) in `src/commands/`. Register it in `src/commands.ts`.
3. When accessing state from a tool: use `context.getAppState()` for reads. Use `context.setAppState(prev => ({...prev, field: newValue}))` for writes. Never use module-level globals.
4. When spawning background work: create a Task via `TaskCreateTool` or spawn a local agent task. Tasks are tracked in `AppState.tasks` and live in disk-backed output files.

## In the source

```typescript
// Source: src/Tool.ts
export type Tool = {
  aliases?: string[]
  call(
    args: z.infer,
    context: ToolUseContext,
    canUseTool: CanUseToolFn,
    parentMessage: AssistantMessage,
    onProgress?: ToolCallProgress,
  ): Promise>
  description(
    input: z.infer,
    options: {
      isNonInteractiveSession: boolean
      toolPermissionContext: ToolPermissionContext
      tools: Tools
    },
  ): Promise
  readonly inputSchema: Input
  isConcurrencySafe(input: z.infer): boolean
  isReadOnly(input: z.infer): boolean
  isDestructive?(input: z.infer): boolean
  interruptBehavior?(): 'cancel' | 'block'
}
```

`canUseTool` is passed into `call()` rather than called before it — this lets tools that spawn sub-tools forward the permission function to their children. `onProgress` is optional, used for streaming partial results to the UI while the tool runs. `isConcurrencySafe()` and `isReadOnly()` are per-call decisions (they receive the input), not per-tool constants.

## Apply it to your code

**Before** — a tool written as a plain function:
```typescript
async function readFile(path: string, maxLines?: number): Promise {
  const content = await fs.readFile(path, 'utf-8')
  return content
}
```

**After** — same capability as a proper Tool:
```typescript
// Source: src/tools/FileReadTool/FileReadTool.ts
// inputSchema drives LLM JSON schema, validation, and TypeScript types simultaneously
const inputSchema = lazySchema(() =>
  z.strictObject({
    file_path: z.string().describe('Absolute path to the file to read'),
    limit: z.number().int().positive().optional().describe('Max lines to read'),
    offset: z.number().int().nonnegative().optional().describe('Line to start reading from'),
  })
)

export const FileReadTool = buildTool({
  name: FILE_READ_TOOL_NAME,
  // isConcurrencySafe: reading never mutates, safe to run in parallel
  isConcurrencySafe() { return true },
  isReadOnly() { return true },

  async checkPermissions(input, context) {
    return checkReadPermissionForTool(FileReadTool, input, context.getAppState().toolPermissionContext)
  },

  async call({ file_path, limit, offset }, context, _canUseTool?) {
    const content = await readFileInRange(file_path, offset, limit)
    // Return data to the LLM as a structured tool result block
    return { data: { type: 'text', file: { filePath: file_path, content } } }
  },

  async description(input) {
    // Description is shown to the user (not the LLM) in permission prompts
    return `Read ${input.file_path}`
  },

  get inputSchema() { return inputSchema() },
})
```

## Signals that you need this pattern

- You're writing a new capability directly in the query loop or as a side effect of another tool
- You have a utility function that needs permission checking but is called ad-hoc
- You're storing conversation-scoped state in a module-level variable
- A tool is importing AppState directly rather than reading it from `context.getAppState()`
- You're creating a command that needs access to tools but can't find how to wire it in

## Signals that you're over-applying it

- A simple utility function that performs pure computation (path joining, string formatting) does not need to be a Tool
- Not every helper needs ToolUseContext — pass only the fields it actually needs
- Don't create a Task for work that completes in milliseconds; Tasks are for long-running or interruptible work

## Works with

- `tool-definition` — the complete guide to implementing a Tool correctly
- `permission-system` — how `canUseTool` works and how to define permission rules
- `task-system` — how to spawn and track background work from a Tool
- `async-concurrency` — how `isConcurrencySafe` affects parallel execution

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TechyMT](https://github.com/TechyMT)
- **Source:** [TechyMT/claude-code-superpowers](https://github.com/TechyMT/claude-code-superpowers)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-techymt-claude-code-superpowers-domain-model
- Seller: https://agentstack.voostack.com/s/techymt
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.