Skip to content

Setup for AI-Assisted Development

New to AI-assisted development on this project? Complete this setup first for your local environment, then follow the AI development workflow.

Note

The core principle of this project's AI development workflow is design before code, built around Claude Code. If you don't use Claude Code, see the section below.

Do I need this?

Situation Action
You plan to use Claude Code for feature work Required — complete this page, then follow the recommended AI development workflow
You want occasional AI assistance and plan to use the Claude Agents, but won't adopt the full workflow Optional — at minimum, install Claude Code; skip the skills plugin setup below
You're getting the project running, fixing a quick bug, or don't plan to use AI tooling Skip for now — nothing here is needed to run the project or contribute code

Install Claude Code

  1. Purchase a Claude subscription.
  2. Install Claude Code by following the official docs.

Set Up Claude Skills and Plugins

Skills are reusable instruction sets that guide Claude through specific workflows. Plugins are collections of skills installed from a marketplace. OCS uses both.

OCS project-specific skills

These are in the .claude/skills/ folder and are active automatically — no installation needed.

Refer to relevant documentation for details on the skills in this folder.

Superpowers plugin for design-before-code skills

The OCS team's recommended AI development workflow follows a design-before-code process. The superpowers plugin provides the skills that guide Claude through each phase — exploring the problem, planning the implementation, executing it, and reviewing the result.

Install it from the official Claude plugin marketplace: https://claude.com/plugins/superpowers

Dimagi plugin skills

The dimagi-claude-workflows repository contains reusable Dimagi Claude workflows, commands, and configuration. OCS uses the dev-utils plugin so its skills (create-pr, iterate-pr, review-plan, etc.) are auto-loaded by claude-code-action in CI as well as in local sessions.

The project's .claude/settings.json already registers the dimagi-claude-workflows marketplace and enables the dev-utils plugin automatically — no installation needed.

To enable other recommended plugins, open the dimagi-claude-workflows repository and follow the setup instructions in plugins/README.md for:

  • code-review — AI code review workflows with specialist agents

What's in the project for Claude-assisted development

OCS ships with instruction files that shape how AI agents work in this codebase. They are already checked in and active — you don't need to configure them.

Code Agent instruction files

  • AGENTS.md — the primary instruction file. Covers architecture, conventions, key paths, do/don't rules, and which docs to consult for specific areas.
  • CLAUDE.md — a file named for Claude Code; a one-line file that points to AGENTS.md.
  • VISION.md — project philosophy. Available for reference when making architectural decisions.
  • CONTEXT.md — domain glossary for the project's terminology. Agents use it to name things consistently. Referred to by AGENTS.md.
  • docs/agents/domain.md — describes how agents use the domain glossary (CONTEXT.md) and Architecture Decision Records (docs/adr/) when exploring the codebase.

Domain guides (docs/agents/)

Contextual guides for specific areas of the codebase. AGENTS.md tells the agent which file to read and when — they are not all loaded at startup, keeping agent context lean while providing depth on demand.

Claude Code settings

.claude/settings.json pre-approves safe commands (pytest, ruff, git, gh, etc.) so Claude Code runs them without prompting, and configures hooks for session startup.

Other AI coding tools

Other agentic coding tools (Gemini CLI, Codex CLI, OpenCode, Aider, Cline, etc.) can follow a similar AI development workflow. Refer to your tool's documentation for details.

What works with any AI tool

  • AGENTS.md — Most AI tools load this automatically.
  • VISION.md and CONTEXT.md — tool-agnostic; can be referenced by any AI coding tool.
  • Domain guides (docs/agents/) — Contextual guidance for specific code areas. Tool-agnostic.

What is Claude-specific

  • Skills — Claude-specific and not available in other AI tools.
  • Safe commands — .claude/settings.json contains pre-approved automation-friendly commands (for tests, linting, version control, file search). Refer to your tool's documentation to configure similar permissions.

Example: Gemini CLI

Google's CLI agent reads GEMINI.md natively. Create a symlink:

ln -s AGENTS.md GEMINI.md

Add the symlink to .gitignore — don't commit it.