project-architect

Project Architect

Front-load your architecture decisions. Keep your context window clean.

A Claude skill that interviews you about your project idea, makes smart architectural decisions, generates lean architecture docs, and scaffolds the actual project — folder structure, git repo, pre-commit hooks, .claude/rules/, and session safety infrastructure. Everything starts as skeletons and grows with your project.

"At project start you know the LEAST about your project. Bloated Day 1 docs waste Claude's context window on speculation. Start lean — decisions and constraints only — and grow docs as the project reveals what actually matters."

/project-architect

What It Does

INTERVIEW              DECIDE                  GENERATE                SCAFFOLD
┌──────────┐          ┌──────────┐            ┌──────────────────┐   ┌──────────────────┐
│ Round 1   │          │ Analyze  │            │ CLAUDE.md        │   │ Folder structure  │
│ Vision    │          │ project  │            │ MEMORY.md        │   │ .gitignore        │
│           │───────▶  │ shape    │──────────▶ │ DOMAIN_ONTOLOGY  │──▶│ .env.example      │
│ Round 2   │          │          │            │ AI_STRATEGY.md   │   │ .claude/rules/    │
│ Deep Dive │          │ Pick the │            │ BACKEND.md       │   │ AI_HANDOFF.md     │
│           │───────▶  │ right    │──────────▶ │ FRONTEND.md      │──▶│ pre-commit hooks  │
│ Round 3   │          │ docs for │            │ DATABASE.md      │   │ git init          │
│ Confirm   │          │ THIS     │            │ ROADMAP.md       │   │ initial commit    │
│           │───────▶  │ project  │──────────▶ │ + more as needed │──▶│ push instructions │
└──────────┘          └──────────┘            └──────────────────┘   └──────────────────┘

Context Window Management

Every .md file the skill generates gets loaded into Claude's context at the start of every future session. Bloated docs = less room for code. The skill enforces a strict budget:

Doc	Day 1 target	Grows to
CLAUDE.md	40-70 lines	~100 (stable)
MEMORY.md	15-25 lines	Most valuable by session 20
ROADMAP	40-60 lines	Updates per phase
BACKEND.md	30-50 lines	Grows with services
AI_STRATEGY.md	30-50 lines	Grows with prompts
All others	20-40 lines	Grows as built

Total Day 1 budget: ~300 lines / ~6-8K tokens across all docs.

The docs grow naturally — each coding session adds detail to the relevant doc as real decisions happen. By session 20, your architecture docs are rich and battle-tested because they grew from real code, not upfront speculation.

Not a template dump. The skill decides which docs your project actually needs:

• Building a CLI tool? You get CLAUDE.md + BACKEND.md + ROADMAP. No frontend docs, no database docs.
• Building an AI-powered SaaS? You get the full stack: AI_STRATEGY.md, DOMAIN_ONTOLOGY.md, SECURITY.md, and everything else.
• Building a simple dashboard? You get minimal docs. The skill respects "keep it simple."

Why This Exists

After building a full-stack AI travel app across 40+ coding sessions, we learned two things:

1. Every doc exists because something went wrong without it:

• CLAUDE.md prevents file truncation, unauthorized merges, and lost work from context exhaustion
• DOMAIN_ONTOLOGY.md prevents the LLM from hallucinating wrong categories
• AI_STRATEGY.md prevents prompt architecture drift and undocumented model decisions
• IMPLEMENTATION_ROADMAP.md prevents scope creep and unbounded sessions

2. Bloated docs are as bad as no docs:

• 200-line docs full of speculation eat context window for zero value
• Claude reads every .md at session start — fat docs mean less room for real work
• Docs that grew organically from real decisions were 10x more useful than docs pre-written on Day 1

The skill encodes both lessons: front-load the thinking, but keep the writing lean.

Quick Start

Option A: Plugin Install (Recommended)

In Claude Code:

/plugin marketplace add sairajesh711/project-architect
/plugin install project-architect@project-architect

Restart Claude Code after installing. Then:

/project-architect

Option B: Manual Install

git clone https://github.com/sairajesh711/project-architect.git
cd project-architect

# Global install (all projects):
./scripts/install.sh --claude --global

# Or local install (current project only):
./scripts/install.sh --claude --local

Option C: Copy Directly

git clone https://github.com/sairajesh711/project-architect.git

# Copy to your project
cp -r project-architect/.claude/skills/project-architect .claude/skills/project-architect
cp project-architect/.claude/commands/project-architect.md .claude/commands/project-architect.md