# 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-talont-org-autoskillit-arch-lens-operational`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TalonT-Org](https://agentstack.voostack.com/s/talont-org)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** https://github.com/TalonT-Org/AutoSkillit/tree/main/src/autoskillit/skills_extended/arch-lens-operational

## Install

```sh
agentstack add skill-talont-org-autoskillit-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 `/autoskillit:arch-lens-operational` or `/autoskillit:make-arch-diag operational`

## Critical Constraints

**NEVER:**
- Modify any source code files
- Include internal implementation details
- Show code-level patterns
- Run subagents in the background (`run_in_background: true` is prohibited)

**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 `/autoskillit:mermaid` skill using the Skill tool - this is MANDATORY
- If the Skill tool cannot be used (disable-model-invocation) or refuses this invocation, do NOT proceed with diagram creation. Abort this step and omit the diagram from output.
- After writing the diagram file, emit the **absolute path** as a structured output
  token as your final output. Resolve the relative `temp/arch-lens-operational/...`
  save path to absolute by prepending the full CWD:
  ```
  diagram_path = /absolute/cwd/temp/arch-lens-operational/{filename}.md
  ```
  This token is MANDATORY — the pipeline cannot proceed without it.

## Arguments

`/autoskillit:arch-lens-operational [context_path]`

- **context_path** (optional) — Absolute path to a PR context file containing new files
  (★-prefixed) and modified files (●-prefixed) from the PR diff. When provided, read
  this file before beginning analysis and focus the diagram on the architectural areas
  affected by these specific files. When absent, explore the full CWD.

---

## Analysis Workflow

### Step 0: Read PR context (when provided)

If a `context_path` positional argument is present:
1. Read the file at `context_path`
2. Extract: new files list (★-prefixed), modified files list (●-prefixed)
3. Focus Step 1 exploration on the modules/components these files belong to
4. Apply ★ prefix on diagram nodes representing new files/components
5. Apply ● prefix on diagram nodes representing modified files/components

If no `context_path` is provided, skip this step and explore the full CWD in Step 1.

### 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, {{AUTOSKILLIT_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: `{{AUTOSKILLIT_TEMP}}/arch-lens-operational/arch_diag_operational_{YYYY-MM-DD_HHMMSS}.md` (relative to the current working directory)

After writing the diagram file, emit a structured output line:

> **IMPORTANT:** Emit the structured output tokens as **literal plain text with no
> markdown formatting on the token names**. Do not wrap token names in `**bold**`,
> `*italic*`, or any other markdown. The adjudicator performs a regex match on the
> exact token name — decorators cause match failure.

```
diagram_path = {absolute_path_to_diagram_file}
```

---

## 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━━━━━━━━━━{{AUTOSKILLIT_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 `/autoskillit: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

- `/autoskillit:make-arch-diag` - Parent skill for lens selection
- `/autoskillit:mermaid` - MUST BE LOADED before creating diagram
- `/autoskillit:arch-lens-development` - For build tooling view
- `/autoskillit: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:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** [TalonT-Org/AutoSkillit](https://github.com/TalonT-Org/AutoSkillit)
- **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-talont-org-autoskillit-arch-lens-operational
- Seller: https://agentstack.voostack.com/s/talont-org
- 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%.