rails-cto-architect

The systems architect. Turns specs and feature requests into executable, task-by-task implementation plans before any code is written.

What it does

rails-cto-architect is the planning phase of the plugin. When a multi-step feature or spec lands, this skill activates before any code gets written. It produces a complete implementation plan optimized for rails-cto-engineer to execute task by task.

The architect follows a structured pipeline:

1. Discovery — If the spec is vague, it interviews you one question at a time until every ambiguity is resolved. No speculative plans.
2. Codebase recon — Launches parallel Explore agents to map existing models, patterns, and test conventions. Reuse before create.
3. Gem research — Evaluates 2–3 candidate gems per subsystem (stars, last release, Rails 8 compatibility, license) and picks one with a written rationale — or explicitly justifies vanilla Rails.
4. Long-term review — Walks the proposed design against four lenses: maintainability, extensibility, scalability, and tech debt.
5. Architecture decisions — Documents data model, service/command boundaries, background job strategy, and authorization before a single line of code exists.
6. Task decomposition — Breaks work into bite-sized, 2–5 minute tasks with checkbox syntax, full code blocks, exact commands, and sub-skill annotations so the engineer knows which playbook to follow.

Plans are saved to .rails-cto/plans/ (gitignored) and always end with /rails-cto-qa as the final mandatory task. Plans never contain commit steps, placeholders, or "implement later" hand-waving.

When it triggers

The architect fires when:

• You say "plan", "architect", "design this", "how should I build X", or similar planning phrases
• The orchestrator detects a multi-step feature request with no existing plan
• You paste long-form requirements or reference a spec file
• Any multi-file change is about to begin without an approved plan

It runs on the opus model for deeper reasoning on complex architectural decisions.

Example

You: I need to add a tagging system to posts — users should be able to
     create tags, assign multiple tags to a post, and filter posts by tag.

Agent: I'm using the rails-cto-architect skill to create the
       implementation plan.

       [interviews for missing details: authorization, tag limits,
        case sensitivity, URL structure]
       [explores existing models, controllers, and test patterns]
       [evaluates acts-as-taggable-on vs vanilla has_many :through]
       [produces .rails-cto/plans/2026-04-18-post-tagging.md with
        5 phases, 22 tasks, full code blocks, and test commands]

       Plan saved. Review the plan, then say "build it" and I'll
       hand off to rails-cto-engineer to execute task by task.

View source

skills/rails-cto-architect/SKILL.md on GitHub →