AI-Assisted Development

This project treats AI-assisted development as a team practice, not just a personal shortcut. For the philosophy behind this approach, see the "How We Build" section in VISION.md.

The development workflow is built around Claude Code and plugin skills, though other agentic coding tools can follow the same process. For tool installation and plugin setup, see AI Tool Setup.

The workflow relies on skills from the Superpowers plugin, listed in Key Skills below.

Recommended Workflow

The core principle is design before code. Every non-trivial change should go through a design phase where the approach is reviewed by the core team before implementation begins.

flowchart TD
    A([Pick an Issue]) --> B["Design<br/>Use brainstorming skill"]
    B --> C["Post Design to Issue<br/>For human review"]
    C --> D{Core Team Approval?}
    D -- No --> B
    D -- Yes --> E["Implementation Plan<br/>Use writing-plans skill"]
    E --> F["Execute Plan<br/>Build + Test"]
    F --> G["Code Review<br/>Specialist agents"]
    G --> H["Open PR<br/>Resolve comments + CI"]
    H --> I([Complete])

1. Design

When starting work on an issue, use your agentic coding tool to explore the codebase and produce a design document. In Claude Code, the brainstorming skill guides this process — it helps you understand the problem, explore approaches, and arrive at a concrete design.

The design should cover:

• What problem is being solved and why
• The chosen approach and alternatives considered
• Key technical decisions and trade-offs
• How the change fits into the existing architecture

2. Human Review

Post the design as a comment on the GitHub issue for review by the core team. Do not proceed to implementation until the design is approved. This catches misunderstandings and architectural mismatches early, before time is spent writing code.

For simple bug fixes or small changes where the approach is obvious, a brief comment describing the fix is sufficient. The goal is alignment, not ceremony.

3. Implementation Planning

Once the design is approved, create a detailed implementation plan. In Claude Code, the writing-plans skill produces a step-by-step plan with file-level changes, test requirements, and dependency ordering.

4. Execute

Work through the implementation plan. The agentic tool can assist with code generation, test writing, and iterating on failures. Review and steer each step as you go — the tool is a collaborator, not an autopilot. In Claude Code, use the test-driven-development skill to write tests before implementation.

5. Code Review and PR

Before opening a PR, run the project's linters, type checkers, and tests. Use code review agents to catch issues early. Then open a PR following the project's pull request guidelines.

Key Skills

These are the Claude Code skills referenced in the workflow above. If your tool has equivalent capabilities, use those instead.