designing-architecture

Files (14)

• SKILL.md
• evals.json · evals/
• feat-offline-queue.md · evals/fixtures/phasewave/.opencode/plans/
• AGENTS.md · evals/fixtures/phasewave/
• ROADMAP.md · evals/fixtures/phasewave/
• schema.sql · evals/fixtures/phasewave/db/
• timer.spec.ts · evals/fixtures/phasewave/e2e/
• package.json · evals/fixtures/phasewave/
• focus-timer.ts · evals/fixtures/phasewave/src/stores/
• client.ts · evals/fixtures/phasewave/src/supabase/
• database.types.ts · evals/fixtures/phasewave/types/
• plan-format.md · references/
• nextjs-supabase.md · references/stacks/
• vue-supabase.md · references/stacks/

SKILL.md (first lines)

# Designing Architecture

Turn one selected work item into a plan artifact that a separate build
session can execute without having been part of the design conversation.
A design pass is **done** when the plan artifact exists, every acceptance
criterion is an observable, independently-verifiable check, and the user
has approved it. The skill stops at approval — it is planning-only. It
does not implement, run migrations, or edit source.

## The design pass

Copy this checklist and check off items as you complete them.

```
Design Progress:
- [ ] 1. Take one item (roadmap entry or direct request)
- [ ] 2. Resolve plan path & slug (configurable; revise-don't-clobber)
- [ ] 3. Detect stack & load the matching stack reference
- [ ] 4. Research the codebase
- [ ] 5. Extract goal, acceptance criteria, boundaries (ask if vague)
- [ ] 5b. UX consult: council-ux on user-facing items (never a silent result — fallback or skip recorded)
- [ ] 6. Draft the plan artifact (full format in references/plan-format.md)
- [ ] 7. Self-check: every criterion is verifiable
- [ ] 8. Present summary + approval question; STOP
```

### Step 1 — Take one item

Take a single work item: one roadmap entry (identified by ID or "the
Nth from the roadmap") or one direct feature request. If the user gives
you a backlog or a pile of items, that is triage, not design — point them
at the `triaging-requirements` skill and stop. A design pass scopes to
one item so the plan can be executed cold by someone who was not in the
conversation.

If the user references a roadmap, read the entry for the named ID and
treat it as the seed for goal + scope. Do not plan the whole roadmap.

### Step 2 — Resolve plan path & slug

Read the project rules file (`AGENTS.md` / `.opencode/agents.md`) for a
`plans_dir:` or `plans:` key. Default to `.opencode/plans/` if none. The
plan file is always `<plans_dir>/<slug>.md`; the slug is the roadmap ID
when one exists, otherwise lowercase-kebab derived from the feature.

If a plan file already exists for the slug, **revise in place** —
preserve the frontmatter history and prior sections, append a dated
revision block, and add a `## History` entry. Never clobber. See the
"Revising an existing plan" section of
[references/plan-format.md](references/plan-format.md). If the approach
has fundamentally changed, supersede the old plan with a new slug and
point at it; do not silently replace.

### Step 3 — Detect stack & load the matching stack reference

Identify the project stack from the rules file. If this skill bundles a
matching stack reference under `references/stacks/` (resolved against
this skill's own directory — not the project's), read it now and apply
its planning concerns. If none exists, proceed generically and flag the
gap in the plan's Open Questions — the absence of stack-specific
guidance is a finding, not a silent "I'll wing it."

Available stack references:

- vue-supabase → [references/stacks/vue-supabase.md](references/stacks/vue-supabase.md)
  Read when the project is Vue 3 + Pinia + Supabase (Postgres + Auth +
  RLS) with a PWA / offline outbox. Applies schema-first planning,
  generated-types handling, RLS planning, and offline/PWA checks.
- nextjs-supabase → [references/stacks/nextjs-supabase.md](references/stacks/nextjs-supabase.md)
  Read when the project is Next.js (App Router) + Supabase (Postgres +
  Auth + RLS) with `@supabase/ssr` cookie sessions. Applies schema-first
  planning, generated-types handling, RLS planning, SSR auth checks, and
  the hybrid server/client data-access decisions.

### Step 4 — Research the codebase

Read the files the plan will touch and the files the feature will reuse:
stores, the data-access client, the schema and generated types, the test
setup, and the rules file's verification commands. Ground every
`Files to Modify` entry in files you actually read — a plan that names a
path you never opened is a guess, and a cold implementer will pay for
that guess. When a feature touches a schema, always read both the schema
source of truth (`db/schema.sql` or equivalent) **and** the generated
types file, so the plan describes the round trip, not just one side.

### Step 5 — Extract goal, acceptance criteria, boundaries

Pull three things out of the item + your research:

1. **Goal** — one sentence: what the feature achieves, stated as the
   user-facing outcome, not the implementation.
2. **Acceptance criteria** — observable behaviors with verifiers. This
   is the heart of the skill; downstream unit / integration / e2e skills
   consume these. Each criterion names the observable behavior **and** how
   to verify it (test command, Playwright selector, SQL/RLS query result,
   exit code, diff). A criterion that restates the feature description
   ("the timer works offline") without a verifier is incomplete — keep
   refining until the verifier is concrete, or move it to Open Questions.
3. **Boundaries** — included and excluded scope. An explicit Excluded
   list is what lets an implementer refuse scope creep with a citation.

**Two kinds of ambiguity, treated differently.** The skill asks before
drafting only when ambiguity is about *what feature is being built*, not
*how to build it*.

- **Feature-identity ambiguity → ask before drafting.** The request names
  a behavior whose meaning splits into distinct *features* — different
  interpretations produce different acceptance-criteria sets, not just
  different implementations. "Share a timer with someone" is this kind:
  read-only anonymous link, collaborative co-control, and exported
  snapshot are three different features with different data models and
  different observables. Picking one silently builds the wrong feature.
  Ask the dimensions that split the feature identity (read-only vs
  co-control; public vs authenticated; single recipient vs group; live
  vs snapshot). Do not draft until the feature is pinned.

- **Design-decision ambiguity → draft with defaults.** The feature is
  clear from the request and research; what remains open are
  implementation choices, each with a defensible default. "Add teams so

From hierovision/ai-framework, MIT.

More from hierovision/ai-framework