arch-lens-operational
Skill1 starsChanged 8 months agoMITView on GitHub
Create Operational architecture diagram showing CLI workflows, configuration, and observability. Administration lens answering "How is it run and monitored?
- Reads credentials
In this repository59 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arch-lens-c4-containerSkill
- arch-lens-concurrencySkill
- arch-lens-data-lineageSkill
- arch-lens-deploymentSkill
- arch-lens-developmentSkill
- arch-lens-error-resilienceSkill
- arch-lens-module-dependencySkill
- arch-lens-process-flowSkill
- arch-lens-repository-accessSkill
- arch-lens-scenariosSkill
- arch-lens-securitySkill
- arch-lens-state-lifecycleSkill
- audit-archSkill
- audit-bugsSkill
- audit-cohesionSkill
- audit-defense-standardsSkill
- audit-frictionSkill
- audit-implSkill
- audit-testsSkill
- design-guardsSkill
- dry-walkthroughSkill
- elaborate-phaseSkill
- exp-lens-benchmark-representativenessSkill
- exp-lens-causal-assumptionsSkill
- exp-lens-comparator-constructionSkill
- exp-lens-error-budgetSkill
- exp-lens-estimand-claritySkill
- exp-lens-exploratory-confirmatorySkill
- exp-lens-fair-comparisonSkill
- exp-lens-governance-riskSkill
- exp-lens-iterative-learningSkill
- exp-lens-measurement-validitySkill
- exp-lens-pipeline-integritySkill
- exp-lens-randomization-blockingSkill
- exp-lens-reproducibility-artifactsSkill
- exp-lens-sensitivity-robustnessSkill
- exp-lens-severity-testingSkill
- exp-lens-unit-interferenceSkill
- exp-lens-validity-threatsSkill
- exp-lens-variance-stabilitySkill
- id-slopSkill
- implement-worktreeSkill
- investigateSkill
- make-arch-diagSkill
- make-experiment-diagSkill
- make-groupsSkill
- make-planSkill
- make-reqSkill
- make-scenariosSkill
- mermaidSkill
- plan-arcSkill
- rectifySkill
- review-approachSkill
- update-architectureSkill
- update-reqsSkill
- update-specsSkill
- verify-diagSkill
- verify-proposed-diagSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 8 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY
- Distinctive: line 51
Look for: CLI frameworks (Click, argparse, Commander, etc.), entry points, main commands
- Very specific: line 56
Look for: config files (config.yaml, .env, settings.json, application.yml), environment variable usage, configuration libraries
- Very specific: line 61
Look for: Taskfile.yml, Makefile, package.json scripts, Rakefile, scripts/ directory
- Distinctive: line 66
Look for: logging configuration, log files, metrics, activity logs, temp/ output directories
- Distinctive: line 71
Look for: status, health, info, diagnose, check commands
- Distinctive: line 76
Look for: reset, clean, clear, purge, restore commands
- Distinctive: line 80
Document common operator workflows:
- Distinctive: line 89
Configuration: READ from env/files (input to system)
- Distinctive: line 92
Status commands: READ from state to display
- Very specific: line 136
Write the diagram to: temp/arch-lens-operational/arch_diag_operational_{YYYY-MM-DD_HHMMSS}.md
- Distinctive: line 250
Before creating the diagram, verify:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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-operationalor/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
/mermaidskill 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:
cliclass: CLI commandsphaseclass: Configuration sourcesstateNodeclass: State tracking (database, registry)outputclass: Monitoring outputshandlerclass: 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
# 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<br/>━━━━━━━━━━<br/>--flag1 --flag2<br/>Purpose"]
end
subgraph Config ["CONFIGURATION"]
direction TB
ENV["Environment Variables<br/>━━━━━━━━━━<br/>API keys, modes"]
SETTINGS["Config File<br/>━━━━━━━━━━<br/>Project config"]
end
subgraph Registry ["STATE TRACKING"]
direction TB
STATE["State Repository<br/>━━━━━━━━━━<br/>Active state<br/>Progress"]
end
subgraph Monitoring ["OBSERVABILITY"]
direction TB
LOGS["Activity Logs<br/>━━━━━━━━━━<br/>Step-by-step"]
DEBUG["Debug Artifacts<br/>━━━━━━━━━━<br/>temp/ directory"]
end
subgraph Tasks ["TASK COMMANDS"]
direction TB
TASK1["task command<br/>━━━━━━━━━━<br/>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
{command example}Check Status
{command example}Reset/Recovery
{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 viewDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

