Agent Workflows

How AI coding agents work inside an App-name repo. A small catalog of structured workflows keeps agent-written code architecturally sound, and automated checks in CI make the rules non-negotiable.

These workflows are canonical

The workflows and the enforcement script described here are vendored from the canonical claude-skills (Skills wiki). Every Twycis project carries the same set, and the Skills Check gate verifies they are present and unmodified.

ARCHITECTURE.md — the "brain"

ARCHITECTURE.md at the repo root is the single source of truth. Every workflow references it to stay aligned on the tech stack, the strict backend-frontend boundary, security rules, and styling conventions. When an agent is unsure whether a change is allowed, the answer lives here — not in the prompt.

Update the brain through the proper channel

Agents do not silently rewrite the rules. When a request conflicts with ARCHITECTURE.md, the agent triggers /propose-architecture-update rather than overriding the boundary.

The workflow catalog

The workflows live in the repo (e.g. .agent/workflows/) and are invoked as slash commands. Each one loads a focused set of instructions — an "agent personality" — for a specific kind of task.

Command	Purpose	Typical triggers
/architecture-review	Verifies UI/API compliance against the rules	Styling, colours, UI components, "check my work"
/propose-architecture-update	Handles deviations from the rules	Conflicting requests, custom style overrides
/debug-issue	Structured root-cause analysis	Fix, debug, error, broken, 500, crash
/db-migration	Safe schema updates via SQLModel + Alembic	Add column, change DB, "update schema"
/full-stack-extension	Extends existing pages end-to-end	Add a field to a page, show X on screen, link data
/cleanup-temp	Manages temporary/ad-hoc files	Clean up, move scripts, declutter, organise
/update-manual	Keeps the user manual accurate	Add feature, change UI, new field, modify flow
/pr-ready	Final quality gate and verification	Done, submit, finished, "prepare for PR"

How workflows are triggered

There are two ways to engage a workflow.

Semantic triggers (passive)

The agent listens for intent. If you say "change the colour of the Save button", it recognises the styling intent and runs /architecture-review to check the change against the design rules before applying it.

Slash commands (active)

Prepend the command to force a specific path and guarantee no steps are skipped:

/debug-issue The payment page renders a blank screen after login.

This loads the debugging instructions immediately, so the agent follows the structured root-cause process rather than guessing.

Best way of working

1. Be explicit about DB changes. Reach for /db-migration early so the SQLModel schema is updated before any data-dependent UI is written. See Migrations.
2. The "done" ritual. When a feature feels finished, run /pr-ready. It re-runs lints, re-checks the architecture, and produces proof-of-work before you open the PR.
3. Respect the pause. If the agent triggers /propose-architecture-update, it has found a violation of your own rules. Decide whether the rule is outdated or the request was the mistake.
4. Keep docs in sync. When functionality changes, let /update-manual keep the user manual current instead of editing it by hand.

Automated enforcement

Workflows guide behaviour; CI guarantees it. Two gates back the rules so that neither a human nor an agent can route bad code into production.

The architecture linter

scripts/check-architecture.js scans for restricted patterns — most importantly direct Supabase or database calls in the frontend, which violate the strict backend-verifies-JWT boundary (see Auth Flow).

node scripts/check-architecture.js

It runs locally via the Husky pre-commit hook (see Developer Onboarding) and again in CI.

The skills-check gate

CI also runs the skills-check, which confirms the canonical workflows and enforcement script are present and unmodified. If they have drifted or been removed, the build fails. See Skills Check.

The pipeline is the backstop

Every push runs the architecture check and the skills-check (Pipeline Overview). If an agent bypasses the workflow instructions, the build fails before anything reaches test or production.