AI-Assisted Development

Athas is already structured for AI-assisted workflows (contract-first APIs, typed shared packages, and explicit runbooks). This guide standardizes how we add assistant rules, skills, and reusable commands without creating tool lock-in.

Goals

• keep assistant outputs consistent with Athas architecture
• reduce repeated prompt boilerplate for common workflows
• preserve one shared source of truth across AI tools

Recommended structure

Use a shared .agents/ folder as the canonical source, then map provider-specific folders to it.

.
├─ .agents/
│  ├─ agents/
│  │  └─ code-reviewer.md
│  ├─ commands/
│  │  ├─ setup-new-feature.md
│  │  └─ release-drill.md
│  └─ skills/
│     ├─ better-auth-best-practices/
│     │  └─ SKILL.md
│     ├─ dokploy-deployment/
│     │  └─ SKILL.md
│     └─ contract-first-orpc/
│        └─ SKILL.md
├─ .cursor/
├─ .claude/
├─ .github/
├─ AGENTS.md
└─ CLAUDE.md

Rule files

AGENTS.md

Use root-level AGENTS.md as the canonical rules file.

Keep it short and operational. Focus on Athas-specific constraints that AI cannot infer from code:

• module boundary rules (core packages framework-agnostic)
• contract-first oRPC expectations
• Dokploy deploy/rollback defaults
• non-destructive git policy

CLAUDE.md

Use:

@AGENTS.md

This avoids drift between rule files.

Skills (modular for Athas)

Keep skills focused by workflow unit (feature/module/migration/component/release):

1. athas-feature-slice
   • end-to-end feature change across contracts/backend/frontend
2. athas-backend-module
   • module layering and boundary-safe backend refactors
3. athas-db-migration
   • schema + migration changes with forward-safe rollout
4. athas-ui-component
   • reusable component implementation and variant discipline
5. athas-release-fix
   • CI/release gate triage with minimal unblock fixes
6. athas-contract-first-orpc
   • oRPC contract-first changes and compile-time drift prevention
7. athas-dokploy-release-drill
   • staged Dokploy rollout + rollback rehearsal
8. athas-docs-maintenance
   • docs IA, canonical checks, and maintenance-mode updates

Skill directory pattern:

.agents/skills/<skill-name>/SKILL.md

With frontmatter:

---
name: contract-first-orpc
description: Use when editing oRPC contracts, procedures, or shared-api client integration.
---

Commands

Use slash-style command docs for repetitive operations:

• /setup-new-feature -> scaffold and integrate feature slices
• /release-drill -> run staged Dokploy deployment + rollback verification
• /fix-ci-failure -> triage failing workflow and apply minimal fix

Command files live in:

.agents/commands/*.md

Subagents

Useful baseline subagents:

• code-reviewer (readonly): conventions, boundaries, contract drift
• security-auditor (readonly): auth, secrets, billing/webhook surfaces
• docs-auditor (readonly): canonical pointer policy + docs IA consistency

Best practices

• plan before coding: explore -> plan -> implement -> verify
• always include verification criteria (typecheck, depcruise, smoke checks)
• keep prompts scoped to feature/module boundaries
• start a fresh session when context drifts
• treat AI output as draft code and review diffs carefully

Verification commands

Common Athas checks assistants should run after significant changes:

bun run typecheck
bun run depcruise:backend
bun run depcruise:libs
node tools/check-docs-canonical.mjs

For release-readiness workflow:

bun run verify:libs

Related docs

• Development Flow
• Backend Module Workflow
• Module Composition Guide
• Dokploy Deployment Blueprint
• Docs Information Architecture