Skip to main content
skill CX Codex

architect · sethgammon — Claude Code skill: what it does, how to install

architect turns a PRD or task outline into an implementation plan with file trees, data models, and phased build steps.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What architect does

The skill reads a PRD file from .planning/ or scans the local codebase alongside a task description. It writes the result into .planning/architecture-{slug}.md, detailing component breakdowns, database entities, build phases with verifiable end conditions, and a risk register.

When facing non-trivial technical forks like state management or database schemas, it weighs two or three candidates against maintenance cost, risk, and model friendliness. In feature mode, it inspects your existing tree first, keeping the diff focused strictly on added and altered files while tracking baseline tests in Phase 0.

It makes no changes to your source tree during planning: everything sits inside a single markdown spec, meaning you can discard the entire proposal with a single file deletion.

What it helps with

  • Generate complete greenfield system architectures from a PRD
  • Map out changes for existing codebases without causing regressions
  • Document architectural decisions and rejected technical alternatives
  • Prepare phased execution steps with verification conditions for Archon

Example prompts for the agent

  • /architect using the spec at .planning/prd-billing.md
  • Plan the architecture to add user authentication to the current app
  • /architect design the system for a new CLI tool

How to install architect

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill architect -a claude-code

3Manually: put the files in place

~/.claude/skills/architect/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/architect/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about architect

How to install architect in Claude Code?

Run two marketplace commands in sequence: first /plugin marketplace add SethGammon/Citadel, followed by /plugin install citadel@citadel-local.

What does architect do?

It translates product requirements into an implementation architecture, producing file trees, data structures, and phased build steps formatted for execution by Archon campaigns.

Can I use architect without an existing PRD?

Yes. If no PRD exists, it inspects existing project files and package.json, turning your plain-text feature description into an actionable build plan.

Source text

SKILL.md · MIT
---
name: architect
license: MIT
description: >-
  Given a PRD, produces an implementation architecture: file tree, component
  breakdown, data model, and a phased build plan with end conditions that
  Archon can execute directly. Multi-candidate evaluation for key decisions.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - architect
  - architecture
  - design the system
  - file structure
  - plan the build
effort: high
---

# /architect — Implementation Architecture from PRD

## When to Use

**Don't use when:** you already have an architecture and want to implement it (use /marshal or /archon); you need a PRD first (use /prd before /architect).

- After /prd produces an approved PRD (greenfield or feature mode)
- When the user has a clear direction + existing codebase (no PRD needed)
- When /do routes a build request
- When the user has a spec and wants a build plan

## Inputs

One of:
1. A PRD file path (from /prd) — preferred, contains structured requirements
2. A user-provided spec or description + an existing codebase — sufficient
3. Neither — suggest /prd first, but don't hard-gate. If the user has a clear
   direction ("add auth to my app"), that + the existing code IS the input.

## Mode Detection

**Greenfield mode**: PRD exists with `Mode: greenfield`, or no existing source files.
Produces a complete architecture from scratch.

**Feature mode**: PRD exists with `Mode: feature`, OR the user describes a feature
and the project has existing source files. The architecture describes changes to
existing code, not a standalone system.

In feature mode:
- Read the existing file tree FIRST — understand the current architecture before planning changes
- Read key files (package.json, tsconfig, main entry points, existing patterns)
- The File Tree section shows ONLY new and modified files, not the entire project
- Phases include a Phase 0: "Baseline" that records current typecheck/test state
- Every phase's end conditions include "no new typecheck errors" and "existing tests pass"
- The Risk Register includes "regression in existing functionality" as a default risk

## Protocol

### Step 1: READ

**If PRD exists**, read it. Extract:
- Core features (the numbered list)
- Technical decisions (stack choices)
- End conditions (what "done" looks like)
- Out of scope (what NOT to build)
- Integration points (feature mode)

**If no PRD**, read the codebase instead:
- Scan the file tree for structure and conventions
- Read package.json / equivalent for dependencies and scripts
- Read the main entry point(s) to understand the architecture
- Use the user's description as the feature spec
- Infer end conditions from the description ("add auth" → "protected routes return 401 without token")

### Step 2: EVALUATE OPTIONS (for non-trivial decisions)

For decisions with multiple valid approaches — state management, API structure, auth pattern, DB schema, routing — generate 2-3 candidates. Assess each on complexity, risk, maintainability, and LLM-friendliness. Pick the winner and document why. Reject alternatives with reasoning.

Simple decisions (file naming, folder structure, CSS) don't need this — use the PRD's stack choices and move on.

### Step 3: PRODUCE

Write to `.planning/architecture-{slug}.md`:

```markdown
# Architecture: {App Name}
> PRD: .planning/prd-{slug}.md  |  Date: {ISO date}

## File Tree
{Greenfield: complete file tree for v1, every file listed.
Feature mode: ONLY new (+) and modified (~) files.}

## Component Breakdown
### Feature: {name}
- Files: | Dependencies: | Complexity: {low/medium/high}

## Data Model
### {Entity name}
- Fields: {name: type}  |  Relationships: {connections}
{Omit section if no database.}

## Key Decisions
### {Decision}: {chosen approach}
- **Chosen**: {approach} — {reasoning}
- **Rejected**: {alternative} — {why not}

## Build Phases
### Phase N: {name}
- **Goal**: {one sentence}
- **Files**: | **Dependencies**: {or "none"}
- **End Conditions**: [ ] {machine-verifiable}

## Phase Dependency Graph
{Text format: Phase 1 → Phase 2 → Phase 3 / Phase 3 + 4 → Phase 5}

## Risk Register
1. {risk}: {mitigation}
2. {risk}: {mitigation}
3. {risk}: {mitigation}

## Deployment Strategy
{Skip if "deploy later" or static-only.}
- **Platform**: | **Method**: | **Environment variables**: | **Pre-deploy checks**:
{Final phase is "Deploy" when a platform is specified. A failed deploy does NOT fail the campaign.}
```

### Step 4: CONNECT TO CAMPAIGN

Each build phase becomes a campaign phase; end conditions carry over; the dependency graph determines ordering; parallel-safe phases flagged for Fleet.

Present summary to user (file count, phase count, key decisions, estimated complexity) and ask: "Ready to build? This will create an Archon campaign." If approved, write the campaign file.

### Step 5: HANDOFF

```
---HANDOFF---
- Architecture: {app name}
- Document: .planning/architecture-{slug}.md
- Phases: {count}
- Estimated complexity: {low/medium/high}
- Next: Archon campaign ready to execute
- Reversibility: green — delete .planning/architecture-{slug}.md to undo
---
```

## Contextual Gates

**Disclosure:** "Generating architecture plan for [description]. No files modified until you approve."
**Reversibility:** green — creates `.planning/architecture-{slug}.md` only; undo with `rm .planning/architecture-{slug}.md`.
**Trust gates:**
- Any: generate architecture document, evaluate options, connect to campaign.

## Quality Gates

- Every phase has at least one machine-verifiable end condition
- Every key decision documents what was rejected and why
- File tree is complete (no "etc." or "..." placeholders)
- Phase dependencies are explicit (no implicit ordering)
- Risk register has at least 2 entries

## Fringe Cases

**No PRD:** Treat user description + existing codebase as the spec; read file tree and package.json; proceed without requiring a PRD.

**Project already has code:** Use feature mode; read existing architecture first; file tree shows only new/modified files; Phase 0 records baseline typecheck/test state.

**Vague description:** Ask at most 2 clarifying questions; don't block on perfect clarity.

**`.planning/` missing:** Create it; if not possible, output the architecture inline and instruct the user to save it.

## Exit Protocol

```
---HANDOFF---
- Architecture: {app name}
- Document: .planning/architecture-{slug}.md
- Phases: {count}
- Estimated complexity: {low/medium/high}
- Next: Archon campaign ready to execute
- Reversibility: green — delete .planning/architecture-{slug}.md to undo
---
```

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

architect by other authors comes first.

architect backnotprop architect is a Claude Code skill that sketches types, signatures, and module boundaries before coding. It triggers on /architect or when a complex change needs architectural design. CX Codex +1 10,600installs architect jsmastery-pro Structures architectural discovery and writes build specifications into docs/specs/. It helps choose tech stacks and design features before writing any code. CX Codex +1 7,600installs architect jsmastery-pro architect aligns terms and implementation choices before coding, then writes a plan for the developer to confirm. CX Codex +1 1,000installs product-capability affaan-m product-capability turns a PRD, roadmap item or product discussion into a capability plan with constraints, invariants and interfaces spelled out before multi-service work starts. CX Codex +1 6,300installs code-architect official Anthropic code-architect analyzes codebase patterns to produce architectural blueprints with file lists, component interfaces, data flows, and phased build sequences. CX Codex 1,439installs senior-architect sickn33 senior-architect — a skill for designing and reviewing system architecture based on explicit requirements, tradeoffs and evidence. Helps you choose an approach by examining current state, alternatives and risks. CX Codex +1 2,200installs 4-spec challengepost 4-spec turns an approved PRD into a technical blueprint: stack, where it runs, components, data, file structure. The last planning step before code. CX Codex +1 1,800installs prd snarktank prd generates a structured Product Requirements Document for a new feature and saves it to markdown. It clarifies scope with quick questions before any code gets written. CX Codex +1 1,500installs spec owainlewis Writes a feature specification before coding begins. It produces a short PRD with user journeys and a technical design for the implementing agent. CX Codex +1 440installs

From the same set55

The whole set →
marshal The marshal skill for Claude Code parses a task, gathers context from code and project memory, and chains skills. It runs in one session and asks only if it cannot continue. CX Codex +1 ★ 937repo stars test-gen test-gen is a Claude Code skill that generates and runs unit tests matching a project's existing framework, covering happy paths, edge cases, and failures. CX Codex +1 ★ 937repo stars design This skill builds a design manifest from a project’s styles or your preferences. A post-edit hook flags mismatches in edited files. CX Codex +1 ★ 937repo stars live-preview live-preview takes screenshots of components during construction, not after completion. Catches layout regressions and invisible blocks before they propagate. CX Codex +1 ★ 937repo stars cost See token usage and costs for sessions, campaigns, and time periods. Use it to check where spend is going and how quickly it is rising. CX Codex +1 ★ 937repo stars merge-review merge-review scans the fleet worktree merge queue, flags files touched by more than one branch, and suggests a merge order before anything lands in main. CX Codex +1 ★ 937repo stars deploy-steward deploy-steward serializes PR merges into main, tracks CI gates, triggers deploys, and files repair tasks when checks fail. CX Codex +1 ★ 937repo stars prd prd turns an app idea into a structured product requirements document, asking about decisions that affect its shape. Use it before handing a project plan to Archon. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open