# Arch Lens Operational

> Create Operational architecture diagram showing CLI workflows, configuration, and observability. Administration lens answering "How is it run and monitored?

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

## Install

```sh
agentstack add skill-trecek-useful-claude-skills-arch-lens-operational
```

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

## About

# Operational Architecture Lens

**Cognitive Mode:** Operational
**Primary Question:** "How is it run and monitored?"
**Focus:** CLI Workflows, Configuration, Observability, Task Commands

## When to Use

- Need to understand operator/admin perspective
- Documenting CLI commands and workflows
- Analyzing configuration and monitoring setup
- User invokes `/arch-lens-operational` or `/make-arch-diag operational`

## Critical Constraints

**NEVER:**
- Modify any source code files
- Include internal implementation details
- Show code-level patterns

**ALWAYS:**
- Focus on OPERATOR experience
- Show CLI commands and their purposes
- Document configuration hierarchy
- Include monitoring and logging outputs
- BEFORE creating any diagram, LOAD the `/mermaid` skill using the Skill tool - this is MANDATORY

---

## Analysis Workflow

### Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

**CLI Entry Points**
- Find all CLI commands
- Identify command groups and subcommands
- Look for: CLI frameworks (Click, argparse, Commander, etc.), entry points, main commands

**Configuration**
- Find configuration sources
- Identify environment variables
- Look for: config files (config.yaml, .env, settings.json, application.yml), environment variable usage, configuration libraries

**Task Automation**
- Find task runner definitions
- Identify automation scripts
- Look for: Taskfile.yml, Makefile, package.json scripts, Rakefile, scripts/ directory

**Logging & Monitoring**
- Find logging configuration
- Identify observability outputs
- Look for: logging configuration, log files, metrics, activity logs, temp/ output directories

**Status & Health**
- Find status/health commands
- Identify diagnostic outputs
- Look for: status, health, info, diagnose, check commands

**Reset & Recovery**
- Find reset/cleanup commands
- Identify recovery operations
- Look for: reset, clean, clear, purge, restore commands

### Step 2: Map Operator Workflows

Document common operator workflows:
- **Create**: How to start new work
- **Run**: How to execute
- **Monitor**: How to check status
- **Debug**: How to diagnose issues
- **Reset**: How to recover from errors

**CRITICAL - Analyze Read/Write Direction:**
For EVERY operational component:
- **Configuration**: READ from env/files (input to system)
- **State tracking**: Does the system READ and WRITE, or just WRITE?
- **Logs/monitoring**: Typically WRITE-only (system writes, humans read)
- **Status commands**: READ from state to display

Clearly categorize:
- **State (read/write)**: System reads back to make decisions
- **Artifacts (write-only)**: System writes for human inspection, never reads back
- **Config (read-only)**: System reads but doesn't modify

### Step 3: Document Configuration Hierarchy

Example pattern (adjust to actual system):
```
1. Environment Variables (highest priority)
2. Secret files (e.g., .secrets.toml, .env.local)
3. Project config (e.g., config.yaml, settings.json)
4. Defaults (lowest priority)
```

### Step 4: Create the Diagram

Use flowchart with:

**Direction:** `TB` for hierarchical command structure

**Subgraphs:**
- CLI Entry Points (commands)
- Configuration (sources)
- Registry/State (tracking)
- Monitoring (observability)
- Task Commands (automation)

**Node Styling:**
- `cli` class: CLI commands
- `phase` class: Configuration sources
- `stateNode` class: State tracking (database, registry)
- `output` class: Monitoring outputs
- `handler` class: Task automation commands

**Show Relationships:**
- Commands to configuration
- Commands to state tracking
- State to monitoring outputs

### Step 5: Write Output

Write the diagram to: `temp/arch-lens-operational/arch_diag_operational_{YYYY-MM-DD_HHMMSS}.md`

---

## Output Template

```markdown
# Operational Diagram: {System Name}

**Lens:** Operational (Administration)
**Question:** How is it run and monitored?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## CLI Commands Quick Reference

| Command | Purpose | Key Flags |
|---------|---------|-----------|
| {command} | {purpose} | {flags} |

## Operational Diagram

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;

    subgraph CLI ["CLI ENTRY POINTS"]
        direction TB
        CMD1["command-name━━━━━━━━━━--flag1 --flag2Purpose"]
    end

    subgraph Config ["CONFIGURATION"]
        direction TB
        ENV["Environment Variables━━━━━━━━━━API keys, modes"]
        SETTINGS["Config File━━━━━━━━━━Project config"]
    end

    subgraph Registry ["STATE TRACKING"]
        direction TB
        STATE["State Repository━━━━━━━━━━Active stateProgress"]
    end

    subgraph Monitoring ["OBSERVABILITY"]
        direction TB
        LOGS["Activity Logs━━━━━━━━━━Step-by-step"]
        DEBUG["Debug Artifacts━━━━━━━━━━temp/ directory"]
    end

    subgraph Tasks ["TASK COMMANDS"]
        direction TB
        TASK1["task command━━━━━━━━━━Automation"]
    end

    %% FLOWS %%
    CMD1 --> ENV
    ENV --> SETTINGS
    CMD1 --> STATE
    CMD1 --> LOGS
    LOGS --> DEBUG

    %% CLASS ASSIGNMENTS %%
    class CMD1 cli;
    class ENV,SETTINGS phase;
    class STATE stateNode;
    class LOGS,DEBUG output;
    class TASK1 handler;
```

**Color Legend:**
| Color | Category | Description |
|-------|----------|-------------|
| Dark Blue | CLI | Command-line entry points |
| Purple | Config | Configuration hierarchy |
| Teal | Registry | State tracking |
| Dark Teal | Monitoring | Observability outputs |
| Orange | Tasks | Task automation |

## Configuration Hierarchy

| Priority | Source | Example |
|----------|--------|---------|
| 1 (highest) | Environment | `API_KEY=...` |
| 2 | Secret file | .env.local |
| 3 | Config file | config.yaml |
| 4 (lowest) | Defaults | Built-in |

## Operator Workflows

### Create New Work
```bash
{command example}
```

### Check Status
```bash
{command example}
```

### Reset/Recovery
```bash
{command example}
```
```

---

## Pre-Diagram Checklist

Before creating the diagram, verify:

- [ ] LOADED `/mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table

---

## Related Skills

- `/make-arch-diag` - Parent skill for lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/arch-lens-development` - For build tooling view
- `/arch-lens-deployment` - For infrastructure view

## Source & license

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

- **Author:** [Trecek](https://github.com/Trecek)
- **Source:** [Trecek/useful-claude-skills](https://github.com/Trecek/useful-claude-skills)
- **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:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **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-trecek-useful-claude-skills-arch-lens-operational
- Seller: https://agentstack.voostack.com/s/trecek
- 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%.