architecture-first-dev
Architecture-first software router for feature, portfolio, and retrospective audit workflows. Use for non-trivial features, refactors, or redesigns where upfront design pays off; cross-cutting concern
SKILL.mdskills/architecture-first-dev/SKILL.md
GitHubArchitecture-First Development Router
Use one entry point for the architecture-first workflow. Keep this file as the routing spine and load the complete stage specification from references/ only when that stage is selected.
The canonical sequence and worked examples live in 00-quickstart.md. The canonical rationale and component model live in 01-architecture.md. Read the quickstart for navigation questions, stage transitions, and after-stage tips; read the architecture document when the pipeline shape or responsibility boundaries are at issue.
Routing decision tree
What does the user need?
│
├─ Orientation, current state, or "what next?"
│ → status
│
├─ One feature or refactor
│ │
│ ├─ Need codebase cartography
│ │ → map
│ ├─ Need independent or iterative expert lenses
│ │ → review
│ ├─ Need consensus across two or more reviews
│ │ → synthesize
│ ├─ Need architecture, behavior, and ADRs
│ │ → design
│ ├─ Need a fresh consistency verdict on existing design files
│ │ → architect
│ ├─ Need phased decomposition of an approved feature design
│ │ → plan
│ ├─ Need implementation of an existing plan
│ │ → external implement command
│ ├─ Need plan/design-to-code drift verification
│ │ → verify
│ └─ Need a consolidated Mermaid view
│ → diagram
│
├─ Two or more related features with shared touch-points
│ → portfolio/meta workflow
│
├─ Large multi-artifact work whose decomposition needs its own campaign
│ → external decompose command, then external implement command
│
└─ Retrospective cross-cutting architecture audit requested by the user
→ probationary architecture-treemap audit stack
Follow the canonical cadence when state permits:
map → review → synthesize → design → plan → implement → verify
review and synthesize remain conditional. architect, diagram, and status are utility routes. The portfolio layer wraps related per-feature work; the audit stack is a separate retrospective route.
Routing contract
- Inspect the request and existing artifacts, select one route, and read its complete specification before acting.
- Pass the invocation arguments through unchanged. Skills support
$ARGUMENTS,$ARGUMENTS[N], and$N; bind every positional index, remainder, flag, default, rejection, and usage message exactly as the loaded specification defines it. - Treat the loaded reference as authoritative for phases, tools, outputs, gates, and stop conditions. Preserve every human judgment gate.
- Read upstream artifacts named by the selected stage. Honor the no-re-exploration and scribe-on-latest rules carried by the stage specifications.
- After a stage completes, read the matching tips in
00-quickstart.mdand surface the relevant next route. - Keep implementation and large-campaign decomposition at their external command boundaries. Load
commands/implement.mdfor implementation andcommands/decompose.mdfor multi-agent decomposition; their own argument contracts control those routes.
Per-feature references (load on demand)
| Intent | Load | Argument entry |
|---|---|---|
| Build or refresh feature cartography | references/map.md |
$ARGUMENTS[0] slug/path; $ARGUMENTS[1+] context |
| Run reviewer lenses or an iterate round | references/review.md |
$ARGUMENTS[0] slug plus --as, --but, --iterate |
| Collapse two or more reviews | references/synthesize.md |
$ARGUMENTS[0] slug |
| Draft and gate the feature design | references/design.md |
$ARGUMENTS[0] slug; $ARGUMENTS[1+] design notes |
| Re-run the standalone architecture gate | references/architect.md |
$ARGUMENTS[0] slug; $ARGUMENTS[1+] redirects |
| Decompose an approved feature design | references/plan.md |
$ARGUMENTS[0] slug |
| Check implementation drift | references/verify.md |
$ARGUMENTS[0] slug; $ARGUMENTS[1+] phase scope |
| Consolidate feature Mermaid diagrams | references/diagram.md |
$ARGUMENTS[0] slug |
Portfolio, audit, and boundary references (load on demand)
| Intent | Load | Scope |
|---|---|---|
| Produce a fast portfolio snapshot | references/status.md |
$ARGUMENTS optional comma-separated slugs |
| Map, design, apply, or sequence a related feature portfolio | references/portfolio.md |
Full /meta-map, /meta-design, /meta-apply, and /meta-plan specifications; $ARGUMENTS scope survives intact |
| Run the retrospective architecture-treemap stack | references/architecture-treemap-audit.md |
Full /components-extract, /audit-slice, /synthesize-audit, and /architecture-treemap specifications |
| Execute an implementation plan | commands/implement.md |
External command; preserve its $ARGUMENTS and flags |
| Run large-campaign decomposition | commands/decompose.md |
External command; preserve its $ARGUMENTS and flags |
status.md is intentionally separate from the portfolio blob because its frontmatter-and-grep snapshot is a narrow, fast orientation path.
When not to use
- Do not use for one-line fixes, throwaway scripts, or exploratory data analysis.
- Do not use to run a bioinformatics analysis pipeline. Use the assay or interpretation skill that matches the data and question.
Audit-stack status
The architecture-treemap audit stack is retrospective and probationary. Its prune review is due 2026-11-20. Keep it off the navigation autopilot: /audit-slice requires concerns authored by the user, and the complete audit blob controls the refusal, provenance, validation, and rendering contracts.