The architect

Skill jpantsjoha/ai-native-developer-experience/.agents/skills/the-architect

Team-wide AI harness adoption plugin, \w operating model, onboarding and delivery standards coherent human-agent outcomes from day one.

Install

npx -y skills add jpantsjoha/ai-native-developer-experience --skill the-architect

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Architecture decisions, trade-off analysis, and ADR authoring. Trigger when a significant technical decision needs to be made, documented, and owned — not when an implementation detail needs a choice.

SKILL.md

4.0 KB, as published. Nobody here has run it

The Architect

Keep the architecture ladder human-owned. Let the agent draft and diagram, but judgment and sign-off stay with the accountable SME.

This skill is for decisions that persist — the ones that are expensive to reverse, that constrain the system for months, or that affect multiple teams. Implementation details belong in code review. Architecture decisions belong here.

When to use

Choosing between two or more structural approaches (database type, service boundary, communication pattern)
Deciding how to handle a cross-cutting concern (auth, observability, multi-tenancy, data residency)
Designing an integration boundary between systems
Anything that warrants an ADR

Procedure

State the decision to be made — one sentence. If you cannot state it in one sentence, it is not one decision.
Capture the context — what forces, constraints, and requirements make this decision necessary? What is the status quo, and why is it insufficient?
Enumerate the options — at least two credible options. For each:
- What are the benefits?
- What are the costs and trade-offs?
- What does it require from the surrounding system?
- What is the failure mode?
Run the Adversarial Gate on the leading option — before committing, invoke adversarial-gate on the preferred choice. A clean gate result is a prerequisite for committing to the decision.
State the decision — which option is chosen and why. The reasoning must reference the context and trade-offs from step 2-3, not just assert a preference.
Record consequences — what does this decision make easier? What does it make harder? What does it prevent?

Author the ADR — format:

---
status: draft
id: ADR-NNNN
date: <date>
deciders: [<handle>]
---

# ADR-NNNN: <short title>

## Status
draft | approved | superseded

## Context
<forces, constraints, why a decision is needed>

## Decision
<the chosen option and reasoning>

## Consequences
<what becomes easier, harder, or foreclosed>

A decision's lifecycle is visible in both the filename postfix and the status: field: ADR/ADR-NNNN-<slug>-DRAFT.md (status: draft) while under review, renamed to ADR/ADR-NNNN-<slug>-approved.md (status: approved) on approval.

Link from the relevant spec, HLD, or PR — ADRs that are not referenced are not found.

Cloud vendor routing

When a decision touches a specific cloud, invoke the matching expert skill before finalising the ADR, and record which guardrail checklist ran:

Vendor	Skill
Google Cloud	`gcp-expert`
AWS	`aws-expert`
Azure	`azure-expert`
Alibaba Cloud	`alibaba-expert`

Multi-cloud decisions run every relevant checklist; the ADR names them. A cloud decision without its guardrail checklist is an unreviewed decision.

Outputs

ADR/ADR-NNNN-<slug>-DRAFT.md → ADR/ADR-NNNN-<slug>-approved.md on approval
Trade-off summary (can be included in the ADR or a separate HLD section)
Updated architecture/HLD-<feature>.md if the decision changes the HLD

Guardrails

One ADR per decision. Bundling multiple decisions into one ADR obscures accountability.
The ADR captures reasoning, not just the outcome. "We chose Postgres" is not an ADR. "We chose Postgres because our consistency requirements rule out eventual-consistency stores, and our team has no operational experience with Cassandra" is an ADR.
Architecture is not implementation. An ADR about which ORM to use is implementation. An ADR about whether the service owns its own database is architecture.
Supersede, do not edit. When a decision changes, create a new ADR that supersedes the old one. History is the point.