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
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat 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-localThis installs the whole citadel plugin with all its skills
2Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill architect -a claude-code3Manually: put the files in place
~/.claude/skills/architect/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/architect/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill architect -a codex2Manually: put the files in place
.agents/skills/architect/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill architect -a cursor2Manually: put the files in place
.cursor/skills/architect/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install SethGammon/Citadel skills/architect2Manually: put the files in place
.github/skills/architect/SKILL.md1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill architect -a gemini-cli2Platform CLI
gemini skills install https://github.com/SethGammon/Citadel --path skills/architectManually: put the files in place
.devin/skills/architect/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.