# Workbench Architecture

> Architecture and ADR workflows for Workbench CLI. Use when documenting system design, decisions, tradeoffs, or rationale that must be tracked over time.

- Skill: `majiayu000/workbench-architecture-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/workbench-architecture-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/workbench-architecture-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/workbench-architecture-2

---


## Key settings

- `.workbench/config.json`: paths.docsRoot, git.defaultBaseBranch.
- Use `workbench config show --format json` to confirm defaults.

## Core workflows

1. Planning phase: create architecture docs for design intent and scope.
2. When a decision is made or changes, create or update an ADR.
3. Link ADRs and architecture docs to work items and specs.

## Commands

Create an architecture doc:
```bash
workbench doc new --type doc --title "Subsystem overview" --path docs/20-architecture/subsystem-overview.md --work-item TASK-0001
```

Create an ADR:
```bash
workbench doc new --type adr --title "Decision title" --path docs/40-decisions/ADR-YYYY-MM-DD-title.md --work-item TASK-0001
```

Link existing docs to a work item:
```bash
workbench item link TASK-0001 --spec /docs/10-product/spec.md --adr /docs/40-decisions/ADR-YYYY-MM-DD-title.md
```

Sync backlinks:
```bash
workbench doc sync --all
```

## Output

- Architecture docs and ADRs with consistent front matter.
- Work items that reference related specs and ADRs.

## Guardrails

- Use ADRs for decisions, architecture docs for structure and flows.
- Keep ADR status updated (proposed, accepted, superseded, deprecated).
- If an ADR does not exist for a significant decision, create one.