### Start Architecture Decision Session (CLI)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Initiates a new architecture decision session using a specified decision tree and providing a title for the session. This starts the process of documenting architectural choices.

```bash
# Start a decision session
decapod decide start --tree microservice --title "User Management API"
```

--------------------------------

### Install and Initialize Decapod CLI

Source: https://github.com/decapodlabs/decapod/blob/master/README.md

Installs the Decapod command-line interface using Cargo and initializes a new Decapod project. This is the primary method for setting up Decapod in a local environment.

```bash
cargo install decapod
deডapod init
```

--------------------------------

### Get Context Bindings (RPC)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Retrieves the context bindings, which map operations to their corresponding documentation. This helps in understanding available operations and their documentation.

```bash
# Get context bindings (op -> doc mappings)
decapod rpc --op context.bindings
```

--------------------------------

### Structured Logging Example (Rust)

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/architecture/OBSERVABILITY.md

Demonstrates the correct way to implement structured logging in Rust, contrasting it with unstructured string formatting. Structured logging ensures machine-parseability.

```rust
// WRONG: unstructured string
// log!("User {} failed to login after {} attempts", user_id, count);

// RIGHT: structured fields
// info!(user_id = %user_id, attempts = count, "Login failed");
```

--------------------------------

### Decapod Agent Handshake Protocol Example

Source: https://github.com/decapodlabs/decapod/blob/master/docs/CONTROL_PLANE_API.md

Illustrates the command to initiate an agent handshake with Decapod. This command specifies the agent's scope and a proof command to verify its capabilities.

```bash
decapod handshake --scope "<scope>" --proof "decapod validate"
```

--------------------------------

### State Machine Transition History Example (JSON)

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/architecture/OBSERVABILITY.md

Illustrates the structure for recording state machine transitions, including 'from', 'to', 'timestamp', 'actor', and 'reason'. This history is crucial for auditing and debugging.

```json
{
    "from": "pending",
    "to": "active",
    "timestamp": "2026-02-14T10:30:00Z",
    "actor": "agent-claude",
    "reason": "Starting implementation of feature X"
}
```

--------------------------------

### Agent Workflow for Project Creation

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/plugins/DECIDE.md

Illustrates the step-by-step process an agent follows when handling a project creation prompt, from analyzing the user prompt to completing the decision session. It highlights key commands like 'suggest', 'start', 'next', 'record', and 'complete'.

```bash
1. Agent analyzes user prompt
2. decapod decide suggest --prompt "user's prompt"     # Get tree suggestion
3. decapod decide start --tree <id> --title "..."      # Create session
4. Loop:
   a. decapod decide next --session <id>               # Get next question
   b. Present options to user                          # Agent surfaces the question
   c. decapod decide record --session <id> ...         # Record answer
5. decapod decide complete --session <id>              # Finalize
```

--------------------------------

### Decapod CLI Quick Start Commands

Source: https://github.com/decapodlabs/decapod/blob/master/CLAUDE.md

A collection of essential Decapod CLI commands for initiating and managing agent tasks. These commands cover validation, documentation ingestion, session acquisition, RPC operations, and task claiming.

```bash
decapod validate
deçapod docs ingest
deçapod session acquire
deçapod rpc --op agent.init
deçapod rpc --op context.resolve
deçapod todo claim --id <task-id>
```

--------------------------------

### Contract Example (JSON)

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/interfaces/RISK_POLICY_GATE.md

This JSON object defines a contract example, specifying risk tier rules, merge policies, documentation drift rules, and evidence requirements. It is used to configure automated checks and policies within the system.

```json
{
  "version": "1",
  "riskTierRules": {
    "high": [
      "app/api/legal-chat/**",
      "lib/tools/**",
      "db/schema.ts"
    ],
    "medium": [
      "app/ui/**",
      "apps/web/**"
    ],
    "low": [
      "**"
    ]
  },
  "mergePolicy": {
    "high": {
      "requiredChecks": [
        "risk-policy-gate",
        "code-review-agent",
        "harness-smoke",
        "browser-evidence-verify",
        "ci-pipeline"
      ]
    },
    "medium": {
      "requiredChecks": [
        "risk-policy-gate",
        "code-review-agent",
        "ci-pipeline"
      ]
    },
    "low": {
      "requiredChecks": [
        "risk-policy-gate",
        "ci-pipeline"
      ]
    }
  },
  "docsDriftRules": {
    "controlPlaneTouchedRequires": [
      "constitution/interfaces/RISK_POLICY_GATE.md",
      "constitution/interfaces/CLAIMS.md"
    ]
  },
  "evidenceRequirements": {
    "uiOrCriticalFlowChanged": {
      "requireManifest": true,
      "requiredChecks": [
        "browser-evidence-capture",
        "browser-evidence-verify"
      ]
    }
  }
}
```

--------------------------------

### Quick Start Initialization Sequence - Bash

Source: https://github.com/decapodlabs/decapod/blob/master/templates/GEMINI.md

This sequence of commands must be run before any mutations to initialize the Gemini agent and its environment within Decapod. It includes validation, documentation ingestion, session acquisition, and agent/context initialization.

```bash
decapod validate
deapod docs ingest
deapod session acquire
deapod rpc --op agent.init
deapod rpc --op context.resolve
deapod todo claim --id <task-id>
```

--------------------------------

### List Available Documentation Paths (CLI)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Lists all available documentation paths within the Decapod system. This helps users discover what documentation is accessible.

```bash
# List available documentation paths
decapod docs list
```

--------------------------------

### Starting New Work in Git

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/specs/GIT.md

Common Git commands for starting new work. This sequence ensures you are on the latest master branch, create a new feature branch, and check for pending tasks.

```bash
git checkout master
git pull origin master
git checkout -b ahr/work          # Or existing working branch
decapod todo list                  # See what to work on
```

--------------------------------

### Agent Workflow for Project Creation

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/plugins/DECIDE.md

Describes the step-by-step process an agent follows when handling a project creation prompt using the decapod CLI.

```APIDOC
## Agent Workflow for Project Creation

This section details the expected agent flow when handling a project creation prompt.

### Steps:

1.  **Analyze User Prompt**: The agent first analyzes the user's input prompt.
2.  **Suggest Tree**: Use `decapod decide suggest --prompt "user's prompt"` to get tree suggestions.
3.  **Start Session**: Create a new session with `decapod decide start --tree <id> --title "..."`.
4.  **Iterative Questioning Loop**:
    a.  **Get Next Question**: Retrieve the next question using `decapod decide next --session <id>`.
    b.  **Present Options**: The agent must present the available options and rationale to the user.
    c.  **Record Answer**: Record the user's answer with `decapod decide record --session <id> --question <Q> --value <V>`.
5.  **Complete Session**: Finalize the session using `decapod decide complete --session <id>`.

### Guidelines:

*   Agents SHOULD use `suggest` to match prompts to decision trees.
*   Agents MUST present each question's options and rationale to the user, avoiding autonomous choices.
```

--------------------------------

### Install Git Pre-commit Hook

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/specs/GIT.md

Provides the command to install a pre-commit hook for validating commit messages according to the project's conventions. This hook helps enforce commit message standards before commits are finalized.

```bash
decapod setup hook --pre-commit
```

--------------------------------

### Install Decapod Git Hooks

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/specs/GIT.md

Installs Decapod's Git hooks to enforce commit message format and code quality. The commit-msg hook validates conventional commit format, while the pre-commit hook runs code formatting and linting checks.

```bash
decapod setup hook
```

--------------------------------

### RPC Interface Operations

Source: https://context7.com/decapodlabs/decapod/llms.txt

Provides examples of various RPC operations for programmatic agent access.

```APIDOC
## RPC Interface

### Description
The RPC interface allows for structured JSON communication for programmatic agent access.

### Method
POST

### Endpoint
/decapod/rpc

### Operations

#### Initialize Agent Session
Initializes an agent session, a required first step for most RPC operations.

**Operation:** `agent.init`

**Request Example:**
```bash
decepod rpc --op agent.init
```

**Response Example:**
```json
{
  "environment_context": { ... },
  "allowed_next_ops": [ ... ],
  "context_capsule": { ... }
}
```

#### Resolve Context
Resolves context based on the operation and touched paths.

**Operation:** `context.resolve`

**Parameters:**
- **op** (string) - Required - The operation to resolve context for.
- **touched_paths** (array of strings) - Required - Paths that were affected.
- **intent_tags** (array of strings) - Optional - Tags related to the intent.

**Request Example:**
```bash
decepod rpc --op context.resolve --params '{"op": "todo.add", "touched_paths": ["src/auth/"], "intent_tags": ["security"]}'
```

#### Get Context Bindings
Retrieves context bindings, mapping operations to documentation.

**Operation:** `context.bindings`

**Request Example:**
```bash
decepod rpc --op context.bindings
```

#### Get Schema
Retrieves the schema for a given entity.

**Operation:** `schema.get`

**Parameters:**
- **entity** (string) - Required - The name of the entity (e.g., "todo").

**Request Example:**
```bash
decepod rpc --op schema.get --params '{"entity": "todo"}'
```

**Response Example:**
```json
{
  "result": {
    "schema_version": "v1",
    "json_schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }
      }
    }
  }
}
```

#### Store/Upsert Entity
Stores or updates a new entity (e.g., todo, knowledge, decision).

**Operation:** `store.upsert`

**Parameters:**
- **entity** (string) - Required - The type of entity to store/upsert.
- **payload** (object) - Required - The data for the entity.

**Request Example:**
```bash
decepod rpc --op store.upsert --params '{"entity": "todo", "payload": {"title": "Fix login bug", "priority": "high"}}'
```

#### Query Entities
Queries for entities based on specified criteria.

**Operation:** `store.query`

**Parameters:**
- **entity** (string) - Required - The type of entity to query.
- **query** (object) - Required - The query criteria.

**Request Example:**
```bash
decepod rpc --op store.query --params '{"entity": "todo", "query": {"status": "open"}}'
```

#### Run Validation
Executes validation checks via RPC.

**Operation:** `validate.run`

**Request Example:**
```bash
decepod rpc --op validate.run
```

#### Read Request from Stdin
Reads a JSON request from standard input, useful for complex JSON payloads.

**Command:** `echo '{"op": "agent.init", "params": {}}' | decapod rpc --stdin`
```

--------------------------------

### List Available Decision Trees (CLI)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Lists all available decision trees for architecture prompting. Each tree has an ID, name, and a count of questions.

```bash
# List available decision trees
decapod decide trees
# Output:
# [
#   {"id": "web-app", "name": "Web Application", "questions": 6},
#   {"id": "microservice", "name": "Microservice", "questions": 6},
#   {"id": "cli-tool", "name": "CLI Tool", "questions": 4},
#   {"id": "library", "name": "Library / Package", "questions": 4}
# ]
```

--------------------------------

### Architecture Decision Prompting

Source: https://context7.com/decapodlabs/decapod/llms.txt

Commands for guiding architecture decisions using structured decision trees.

```APIDOC
## Architecture Decision Prompting

### Description
Structured decision trees for guiding architecture choices before code implementation.

### Commands

#### List Decision Trees
Lists all available decision trees.

**Usage:** `decapod decide trees`

**Example:**
```bash
decepod decide trees
```

**Output Example:**
```json
[
  {"id": "web-app", "name": "Web Application", "questions": 6},
  {"id": "microservice", "name": "Microservice", "questions": 6},
  {"id": "cli-tool", "name": "CLI Tool", "questions": 4},
  {"id": "library", "name": "Library / Package", "questions": 4}
]
```

#### Suggest Tree
Provides a suggested decision tree based on a user prompt.

**Usage:** `decapod decide suggest --prompt "[prompt_text]"`

**Parameters:**
- **--prompt** (string) - Required - The user's prompt describing the architecture need.

**Example:**
```bash
decepod decide suggest --prompt "build a REST API for user management"
```

#### Start Decision Session
Initiates a new decision-making session.

**Usage:** `decapod decide start --tree [tree_id] --title [session_title]`

**Parameters:**
- **--tree** (string) - Required - The ID of the decision tree to use.
- **--title** (string) - Required - The title for the decision session.

**Example:**
```bash
decepod decide start --tree microservice --title "User Management API"
```

#### Get Next Question
Retrieves the next unanswered question in the current decision session.

**Usage:** `decapod decide next --session [session_id]`

**Parameters:**
- **--session** (string) - Required - The ID of the decision session.

**Example:**
```bash
decepod decide next --session DS_01JXXXXXXXXXXX
```

**Output Example:**
(Includes question prompt, context, and options with rationale)

#### Record Decision
Records a decision for a specific question within a session.

**Usage:** `decapod decide record --session [session_id] --question [question_key] --value [selected_value] --rationale [rationale_text]`

**Parameters:**
- **--session** (string) - Required - The ID of the decision session.
- **--question** (string) - Required - The key of the question being answered.
- **--value** (string) - Required - The selected value for the question.
- **--rationale** (string) - Required - The rationale for the selected value.

**Example:**
```bash
decepod decide record --session DS_01JXXXXXXXXXXX --question runtime --value rust --rationale "Performance critical service"
```

#### Complete Session
Completes the decision session and generates an Architecture Decision Record (ADR).

**Usage:** `decapod decide complete --session [session_id]`

**Parameters:**
- **--session** (string) - Required - The ID of the decision session.

**Example:**
```bash
decepod decide complete --session DS_01JXXXXXXXXXXX
```

#### List Sessions
Lists active or all decision sessions.

**Usage:** `decapod decide session list [--status [status]]`

**Parameters:**
- **--status** (string) - Optional - Filter sessions by status (e.g., "active").

**Example:**
```bash
decepod decide session list --status active
```
```

--------------------------------

### Initialize Agent Session (RPC)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Initializes an agent session, which is a prerequisite for performing most RPC operations. The response includes environment context, allowed next operations, and a context capsule.

```bash
# Initialize agent session (required first step for RPC operations)
decapod rpc --op agent.init
# Response includes: environment_context, allowed_next_ops, context_capsule
```

--------------------------------

### Get Schema for an Entity (RPC)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Fetches the JSON schema for a specified entity, such as 'todo'. This schema defines the structure and properties of the entity.

```bash
# Get schema for an entity
decapod rpc --op schema.get --params '{"entity": "todo"}'
# Output:
# {
#   "result": {
#     "schema_version": "v1",
#     "json_schema": {
#       "type": "object",
#       "properties": {
#         "title": { "type": "string" },
#         "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }
#       }
#     }
#   }
# }
```

--------------------------------

### Get Federation Memory Node Details (CLI)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Retrieves detailed information about a specific node in the federation memory, including its sources and associated edges.

```bash
# Get node with sources and edges
decapod data federation get --id N_01JXXXXXXXXXXX
```

--------------------------------

### List Architecture Decision Sessions (CLI)

Source: https://context7.com/decapodlabs/decapod/llms.txt

Lists active architecture decision sessions, allowing users to view and manage ongoing decision-making processes.

```bash
# List sessions
decapod decide session list --status active
```

--------------------------------

### Retrieving Preferences

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/plugins/TEAMMATE.md

Explains how to retrieve a specific user preference using the `decapod data teammate get` command, essential for agents before performing actions.

```APIDOC
## Retrieving Preferences

### Description

This endpoint allows agents or users to retrieve a specific user preference. It is recommended that agents query preferences before executing actions that might be affected by them.

### Method

`decapod data teammate get`

### Parameters

#### Path Parameters

None

#### Query Parameters

- **`category`** (string) - Required - The domain of the preference.
- **`key`** (string) - Required - The specific identifier within the category.

### Request Example

```bash
decapod data teammate get --category git --key ssh_contributor
```

### Response

#### Success Response (200)

- **`value`** (string) - The stored preference value.
- **`context`** (string) - Optional - The context associated with the preference.

#### Response Example

```json
{
  "value": "user_only",
  "context": "Use user's SSH credentials, never add self as commit contributor"
}
```
```

--------------------------------

### Project Override Configuration

Source: https://github.com/decapodlabs/decapod/blob/master/constitution/plugins/DECIDE.md

Explains how projects can customize the 'decide' subsystem using the `.decapod/OVERRIDE.md` file.

```APIDOC
## Project Override Configuration (`.decapod/OVERRIDE.md`)

Projects can customize the 'decide' subsystem by creating or modifying the `.decapod/OVERRIDE.md` file.

### `plugins/DECIDE.md` Section:

#### Custom Trees
Projects can define additional domain-specific decision trees by extending the 'decide' plugin. Use `decapod feedback propose` to request new trees.

#### Mandatory Questions
Projects can specify mandatory decisions that must be made before code implementation begins. Agents should verify active decision sessions before starting implementation.

#### Decision Policies
*   All new projects MUST have a completed decision session before implementation begins.
*   Decisions can be superseded by initiating a new session for the same decision tree.
```