dev-architect

Files (13)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• ai-agents.md · references/
• data.md · references/
• infra.md · references/
• mobile.md · references/
• pinned-facts.md · references/
• principles.md · references/
• security.md · references/
• stack.md · references/
• web.md · references/
• trigger-queries.json · tests/fixtures/

SKILL.md (first lines)

# VegaStack Dev Architect

Advise: recommend the smallest architecture that meets the requirement and name the
trigger that justifies every moving part.

Brief the team the way
the architecture owner — the person dev.md's `architect:` knob names — would, and record
rather than gate: when the team departs from a recommendation, record it as accepted risk
(one dated line proposed for the decision register) and keep reporting it honestly.
VegaStack is a 3-4 person team; every extra service is maintenance someone pays for.

Nearest neighbors: `dev-setup` writes `.vegastack/dev.md` including its `## Architecture`
section — setup owns the file, this skill owns the judgment reading it. `dev-intake` routes
stack-bearing approach choices here while writing a brief; `vegastack-design-system` owns
component and token choices inside the UI.

## Every task

1. Read the `## Architecture` section of `.vegastack/dev.md`. Section or file missing →
   answer from the repo and suggest running `dev-setup` to record it — unless the project
   deliberately has no app architecture (a tooling/docs repo whose dev.md `stack:` line is
   the whole truth); dev.md is dev-setup's to write, so suggest running it. A legacy
   `.vegastack/arch.md` found instead: treat its lines as the Architecture facts for this
   task and suggest `dev-setup`, which migrates it.
2. The repository is the source of truth — package.json, lockfile, wrangler/CI files, the
   code. The Architecture section is a head start. When they disagree, trust the repo and
   propose the one-line section fix, because a stale line followed silently becomes a
   decision nobody made. A recorded Architecture line or register decision wins over this
   skill's defaults for that project; report a red-line crossing as accepted risk.
3. Load only the references the task touches (table below), because most of the set is not
   this task's.
4. Separate what is fact, what is assumption, and what is the architecture owner's
   recorded decision. A directive tagged "(inferred)" is a researched extrapolation the
   architecture owner has not ratified — confirm on first use, and a confirmation is
   proposed as a register line in conventions' Operator identity format, its decision text
   `ratified: <the directive>`; recording it drops the tag from the reference file in the
   same change, so an inferred directive is ratified or removed, not left to harden into
   practice. Everything untagged is a recorded decision or a verified fact. A blocker
   against a recorded decision is surfaced as a blocker; the decision stands until the
   owner reopens it.
5. Answer at the right size: a question gets the recommendation plus at most one material
   risk, in plain prose. Reviews and migration plans follow the review discipline in
   [principles](references/principles.md).
6. A directional call this work settles — one that passes the Decisions test in dev.md —
   is proposed as one line for the register dev.md names and recorded only on the user's
   yes; `dev-intake` and `dev-ship` own the recording mechanics.

## Verify before you recommend

Any decision-bearing claim about a platform or library — its capability, version, limit,
price, and the name itself, because an invented package, API or option name is the
commonest fabrication — is grounded before it shapes a recommendation:

1. Check [pinned-facts](references/pinned-facts.md) — the verified cache.
2. Cached and verified within 60 days → use it. Older → check that one fact again against
   its source URL (docs tool or web search) first, and say so.
3. Not cached → verify against live official docs before recommending; when the fact is
   durable and decision-changing, propose adding it to pinned-facts.

Refresh one fact at a time, in the task that needs it, because a bulk refresh spends the
session on facts no decision needs; anything unchecked is labelled UNVERIFIED. The other
dev skills cite this protocol instead of restating it.

## Route

| Task touches | Read |
|---|---|
| "should we add X", philosophy of a decision, how to review, phrase, or record | [principles](references/principles.md) |
| stack, vendor, or framework choice | [stack](references/stack.md) |
| a claim about a platform's current capability or version | [pinned-facts](references/pinned-facts.md) |
| UI, Next.js, API design | [web](references/web.md) |
| schema, tenancy, migrations, storage, caching | [data](references/data.md) |
| hosting, deploy, CI cost, observability, incidents | [infra](references/infra.md) |
| realtime, SSE, WebSockets, collaboration | [stack](references/stack.md) + [web](references/web.md) |
| AI/model calls, agents, MCP, jobs, cron, durable work | [ai-agents](references/ai-agents.md) |
| auth, secrets, permissions, PII, external calls | [security](references/security.md) |
| Flutter or a mobile app | [mobile](references/mobile.md) |

## Red lines — hold regardless of project size

The red lines below are the only rules that live both here and in a reference; everything
else has exactly one home file.

- Commit, tag, push, merge, publish, deploy or create paid/cloud resources only on the
  operator's explicit go-ahead for that step, because approval for one step is
  not approval for the next (where the dev workflow is installed, an issue's recorded
  "ship it" covers that issue's PR, merge and cleanup, and nothing else).
- Authorization lives server-side in the data-access layer, checked per resource on every
  request, because the CVE-2025-29927 bypass class is exactly middleware-as-boundary
  (`middleware.ts` or `proxy.ts`).
- Secrets, tokens and credentials live only in the credential store, because plaintext in
  code, config, logs, events or agent state leaks on the first incident; permission checks
  fail closed and the deny is audited.
- Authentication is Better Auth, and teams, organizations and any "user groups" concept
  are its constructs, because a parallel schema forks every permission check.
- Consume the VegaStack design system; a change upstream in it is the architecture owner's
  deliberate decision, because a side-effect component fragments the system.
- **Verified, or labelled UNVERIFIED** — every URL, version, benchmark and "verified"
  claim comes from a checked official source or carries the label, because a fabricated
  fact in an architecture recommendation is the costliest kind.

From vegastack/vegafactory, MIT.

More from vegastack/vegafactory