# Directory Structure ## Overview Claude Code loads `.claude/` from TWO locations: 1. **Home directory** (`~/.claude/`) - always loaded 2. **Current working directory** (`{cwd}/.claude/`) - if exists **Important:** Claude does NOT recursively scan subdirectories. If you run `claude` from `~/Projects/myapp/`, it will NOT find `~/Projects/.claude/`. ## Recommended Structure ``` ~/ # Home directory ├── .gitignore # Ignores project-specific components │ ├── .claude/ # Faion Network Framework (git repo) │ ├── CLAUDE.md # Global instructions │ ├── settings.json # Global settings │ │ │ ├── skills/ # ALL skills (global + project) │ │ ├── faion/ # Global: umbrella knowledge (52 domain knowledge bases, tier-partitioned) │ │ │ └── knowledge/ # ├── free/ (8), solo/ (13), pro/ (24), geek/ (7) │ │ │ # each tier → groups (dev/, ai/, infra/, product/, pm/, ba/, ux/, marketing/, research/, comms/, sdd/) │ │ ├── faion-brainstorm/ # Global: multi-agent brainstorm │ │ ├── faion-feature-executor/ # Global: SDD feature executor │ │ ├── faion-sdd-execution/ # Global: SDD quality gates + reflexion │ │ ├── faion-improver/ # Global: session-based improvement │ │ └── {project}-*/ # Project: gitignored │ │ │ ├── agents/ # ALL agents (global + project) │ │ ├── faion-*-agent.md # Global: committed │ │ └── myapp-*-agent.md # Project: gitignored │ │ │ ├── commands/ # ALL commands │ │ ├── commit.md # Global: committed │ │ └── myapp-*.md # Project: gitignored │ │ │ ├── scripts/hooks/ # ALL hooks │ │ ├── faion-*-hook.* # Global: committed │ │ └── myapp-*-hook.* # Project: gitignored │ │ │ └── docs/ # Framework documentation │ └── directory-structure.md # This file │ └── Projects/ # Projects folder │ ├── myapp/ # Single-repo project │ ├── CLAUDE.md # Project instructions │ ├── src/ # Source code │ ├── .git/ # Git repository │ └── .aidocs/ # SDD documentation │ ├── constitution.md │ ├── roadmap.md │ ├── product_docs/ │ ├── backlog/ │ │ ├── feature-001-auth/ │ │ └── TASK-0001-setup.md │ ├── todo/ │ ├── in-progress/ │ └── done/ │ └── bigapp/ # Multi-repo project ├── CLAUDE.md # Project overview ├── bigapp-fe/ # Frontend repo │ ├── .git/ │ └── src/ ├── bigapp-be/ # Backend repo │ ├── .git/ │ └── src/ └── .aidocs/ # Shared SDD docs for all repos ├── constitution.md # Covers FE + BE ├── roadmap.md ├── product_docs/ ├── backlog/ │ ├── feature-001-auth/ # May touch FE + BE │ └── TASK-0001-api.md ├── todo/ ├── in-progress/ └── done/ ``` ## Key Points 1. **Single `.claude/` directory** in `~/` contains everything 2. **Global components** (`faion-*`) are committed to faion-network repo 3. **Project components** (`{project}-*`) are gitignored 4. **Project CLAUDE.md** lives in project root (not in .claude) 5. **.aidocs/ location:** - **Single repo:** Inside repo root (alongside src/) - **Multi-repo:** Parent level (alongside repo folders) ## Why This Structure? Claude Code always finds `~/.claude/` regardless of where you run it: ```bash cd ~/Projects/myapp && claude # Loads ~/.claude/ ✓ cd ~/Projects/another && claude # Loads ~/.claude/ ✓ cd ~ && claude # Loads ~/.claude/ ✓ ``` All skills/agents are always available, project-specific ones just need gitignore. ## .aidocs/ Placement Rules **Decision tree:** ``` Does the project have multiple repos? ├─ NO (single repo) │ └─ Place .aidocs/ INSIDE repo root │ Example: myapp/.aidocs/ │ └─ YES (multiple repos: FE, BE, mobile, etc.) └─ Place .aidocs/ at PARENT level (alongside repos) Example: myapp/.aidocs/ + myapp/myapp-fe/ + myapp/myapp-be/ <<<<<<< HEAD ======= ``` **Why?** - **Single repo:** .aidocs/ is versioned with code, easier to clone - **Multi-repo:** .aidocs/ is shared, avoids duplication, single source of truth **Examples:** | Project Structure | .aidocs/ Location | Reason | |-------------------|-------------------|--------| | `myapp/` (monorepo) | `myapp/.aidocs/` | Single repo | | `bigapp/bigapp-fe/` + `bigapp/bigapp-be/` | `bigapp/.aidocs/` | Multi-repo, shared docs | | `faion-net/` (Gatsby) | `faion-net/.aidocs/` | Single repo | | `scanmecard/scanmecard-web/` + `scanmecard/scanmecard-api/` | `scanmecard/.aidocs/` | Multi-repo | ## .aidocs Structure SDD (Specification-Driven Development) documentation lives in project's `.aidocs/`: ``` .aidocs/ ├── constitution.md # Immutable project principles │ - Tech stack (for ALL repos in multi-repo setup) │ - Code standards (linters, formatters) │ - Testing requirements │ - Git conventions │ - Multi-repo: describes FE, BE, and shared standards │ ├── roadmap.md # High-level project roadmap │ ├── product_docs/ # Product documentation │ ├── prd.md # Product Requirements │ ├── user-personas.md # Target users │ └── competitive-analysis.md # Market research │ ├── backlog/ # Ideas, not prioritized │ ├── feature-001-auth/ # Feature folder │ │ ├── spec.md # Functional requirements (FR-X) │ │ ├── design.md # Architecture decisions (AD-X) │ │ └── implementation-plan.md # Task breakdown │ └── TASK-0001-setup.md # Standalone task file │ ├── todo/ # Specified, ready to implement │ ├── feature-002-payments/ │ └── TASK-0005-database.md │ ├── in-progress/ # Currently executing │ ├── feature-003-dashboard/ │ └── TASK-0010-api.md │ └── done/ # Completed ├── feature-000-init/ └── TASK-0000-scaffold.md >>>>>>> claude ``` **Why?** - **Single repo:** .aidocs/ is versioned with code, easier to clone - **Multi-repo:** .aidocs/ is shared, avoids duplication, single source of truth **Examples:** | Project Structure | .aidocs/ Location | Reason | |-------------------|-------------------|--------| | `myapp/` (monorepo) | `myapp/.aidocs/` | Single repo | | `bigapp/bigapp-fe/` + `bigapp/bigapp-be/` | `bigapp/.aidocs/` | Multi-repo, shared docs | | `faion-net/` (Gatsby) | `faion-net/.aidocs/` | Single repo | | `scanmecard/scanmecard-web/` + `scanmecard/scanmecard-api/` | `scanmecard/.aidocs/` | Multi-repo | ## .aidocs Structure SDD (Specification-Driven Development) documentation lives in project's `.aidocs/`: ``` .aidocs/ ├── constitution.md # Immutable project principles │ - Tech stack (for ALL repos in multi-repo setup) │ - Code standards (linters, formatters) │ - Testing requirements │ - Git conventions │ - Multi-repo: describes FE, BE, and shared standards │ ├── roadmap.md # High-level project roadmap │ - Feature timeline and phases │ - Release schedule │ - Success metrics and goals │ - Platform metrics │ ├── product_docs/ # Product planning & GTM │ ├── article-lists/ # Editorial calendar │ │ - Content planning │ │ - Publishing schedule │ │ │ ├── gtm-manifest/ # Go-to-market strategy │ │ - Launch strategy │ │ - Marketing channels │ │ - Distribution plan │ │ │ ├── seo/ # SEO keywords & strategy │ │ - Keyword research │ │ - Content optimization │ │ - Search strategy │ │ │ └── [other product docs] # PRD, personas, competitive analysis │ ├── content/ # Content drafts & planning │ └── articles/ # Article drafts (MDX/Markdown) │ - Blog posts │ - Tutorials │ - Documentation │ ├── improvements/ # Feature proposals & enhancements │ ├── README.md # Improvement tracking overview │ └── AI-NNN-*.md # Individual improvement suggestions │ ├── backlog/ # Ideas, ready for grooming │ ├── feature-NNN-name/ # Feature folder │ │ ├── README.md # Feature overview & context │ │ ├── spec.md # What to build (requirements, success criteria) │ │ ├── design.md # How to build (architecture, API contracts) │ │ └── implementation-plan.md # Task breakdown, dependencies, token estimates │ └── TASK-NNNN-title.md # Standalone task file │ ├── todo/ # Specified, ready to execute │ ├── feature-NNN-name/ # Feature folder (all docs ready) │ └── TASK-NNNN-title.md # Ready task │ ├── in-progress/ # Currently executing │ ├── feature-NNN-name/ # Feature being implemented │ └── TASK-NNNN-title.md # Task in progress │ └── done/ # Completed and verified ├── feature-NNN-name/ # Completed feature (archive) └── TASK-NNNN-title.md # Completed task ``` ### Documentation Types | Document | Purpose | Content | |----------|---------|---------| | **constitution.md** | Project foundation | Tech stack, architecture decisions (ADRs), coding standards, multi-repo setup | | **roadmap.md** | Strategic planning | Feature timeline, release schedule, success metrics, platform KPIs | | **spec.md** | Requirements | What to build, functional requirements (FR-X), success criteria, acceptance tests | | **design.md** | Architecture | How to build, technical decisions (AD-X), API contracts, data models, diagrams | | **implementation-plan.md** | Execution plan | Task breakdown with dependencies, complexity estimates, token budgets | | **README.md** | Feature overview | Context, motivation, high-level summary (in feature folders) | ### Folder Purposes | Folder | Purpose | |--------|---------| | **product_docs/** | Product strategy, GTM planning, content calendar, SEO strategy | | **content/** | Article drafts, blog posts, tutorials (MDX/Markdown) | | **improvements/** | Feature enhancement proposals, suggestions from AI analysis | | **backlog/** | Features in grooming phase, not yet ready for implementation | | **todo/** | Fully specified features, ready to execute (spec/design/plan complete) | | **in-progress/** | Currently executing features/tasks | | **done/** | Completed and verified features/tasks (archive) | ## Lifecycle ``` backlog/ → todo/ → in-progress/ → done/ ``` | Status | Description | |--------|-------------| | `backlog/` | Ideas, not yet specified | | `todo/` | Specified (spec.md exists), ready to implement | | `in-progress/` | Currently being implemented | | `done/` | Completed and verified | **Feature Movement:** - Features (folders `feature-NNN-name/`) move with their tasks - Tasks (`TASK-NNNN-title.md`) can move independently - Both follow the same lifecycle path ## Real-World Example: faion-net Multi-repository project with shared `.aidocs/` structure: ``` ~/Projects/faion-net/ ├── CLAUDE.md # Project overview ├── .aidocs/ # Shared SDD docs (ALL repos) │ ├── constitution.md # Tech stack (Gatsby + Django + Go) │ ├── roadmap.md # Feature roadmap & metrics │ │ │ ├── product_docs/ # Product & GTM │ │ ├── article-lists/ # Editorial calendar │ │ ├── gtm-manifest/ # Marketing strategy │ │ └── seo/ # SEO keywords │ │ │ ├── content/ # Content planning │ │ └── articles/ # Blog post drafts │ │ │ ├── improvements/ # Feature proposals │ │ ├── README.md │ │ └── AI-001-*.md │ │ │ ├── backlog/ │ │ └── feature-026-knowledge-infrastructure/ │ │ ├── README.md │ │ ├── spec.md │ │ ├── design.md │ │ └── implementation-plan.md │ │ │ ├── todo/ │ │ └── feature-024-starter-kits/ │ │ ├── spec.md │ │ ├── design.md │ │ ├── implementation-plan.md │ │ └── TASK-SK-*.md # 5 tasks │ │ │ └── done/ │ └── feature-025-cli-tool/ │ ├── spec.md │ ├── design.md │ ├── implementation-plan.md │ └── TASK-CLI-*.md # 7 completed tasks │ ├── faion-net-fe/ # Frontend repo (Gatsby 5) │ ├── .git/ │ ├── CLAUDE.md # FE-specific instructions │ ├── content/ # 502 MDX methodologies │ └── src/ │ ├── faion-net-be/ # Backend repo (Django 5) │ ├── .git/ │ ├── CLAUDE.md # BE-specific instructions │ ├── apps/ # 10 Django apps │ └── manage.py │ ├── faion-cli/ # CLI tool repo (Go, DEPRECATED — replaced by Python Agent SDK pipelines in faion-network/skills/) │ ├── .git/ │ ├── cmd/ # Commands (legacy) │ └── tui/ # Bubble Tea TUI (legacy) │ └── faion-network-storybook/ # Component library (React) ├── .git/ └── stories/ # 62 components ``` **Key points:** - One `.aidocs/` folder for ALL repositories - `constitution.md` covers tech decisions for FE, BE, CLI, Storybook - Features can touch multiple repos (e.g., Starter Kits = BE API + CLI download) - Completed Feature 025 (CLI Tool) → moved from todo/ to done/ with all tasks - Active Feature 024 (Starter Kits) → in todo/, executing TASK-SK-001 ## Naming Conventions ### Global (Faion Network) | Component | Pattern | Example | |-----------|---------|---------| | Skill (orchestrator) | `faion-net` | `faion-net` | | Skill (role-based) | `faion-{role}` | `faion-software-developer`, `faion-ux-ui-designer` | | Skill (process) | `faion-{process}` | `faion-sdd`, `faion-feature-executor` | | Agent | `faion-{name}-agent` | `faion-task-YOLO-executor-opus-agent` | | Hook | `faion-{event}-{purpose}-hook.{ext}` | `faion-pre-bash-security-hook.py` | | Command | `{verb}` (no prefix) | `commit`, `deploy` | ### Project-Specific | Component | Pattern | Example | |-----------|---------|---------| | Skill | `{project}-{name}` | `myapp-auth`, `myapp-deploy` | | Agent | `{project}-{name}-agent` | `myapp-deploy-agent` | | Hook | `{project}-{event}-{purpose}-hook.{ext}` | `myapp-pre-bash-lint-hook.sh` | | Command | `{project}-{action}` | `myapp-build` | ### Features & Tasks | Component | Pattern | Example | |-----------|---------|---------| | Feature folder | `feature-{NNN}-{name}` | `feature-001-auth`, `feature-025-dashboard` | | Task file | `TASK-{NNNN}-{title}.md` | `TASK-0001-user-model.md`, `TASK-0150-api-endpoint.md` | ## Gitignore Setup Add `.gitignore` **at the same level as `.claude/`** (sibling, not inside): ``` ~/ # or ~/Projects/ ├── .gitignore # ← HERE (sibling of .claude/) └── .claude/ # Framework ``` **Content:** ```gitignore # Project-specific Claude components (not committed to faion-network) .claude/skills/* !.claude/skills/faion-*/ .claude/agents/*-*-agent.md !.claude/agents/faion-*-agent.md .claude/commands/*-*.md !.claude/commands/faion-*.md .claude/scripts/hooks/*-*-hook.* !.claude/scripts/hooks/faion-*-hook.* # Local settings .claude/settings.local.json ``` **Simpler alternative** (if you know project names): ```gitignore # Project-specific (myapp) .claude/skills/myapp-*/ .claude/agents/myapp-*.md .claude/commands/myapp-*.md .claude/scripts/hooks/myapp-* # Local settings .claude/settings.local.json ``` ## Quick Setup ### New Single-Repo Project ```bash # Create project directory mkdir -p ~/Projects/myapp cd ~/Projects/myapp # Initialize git git init # Create project CLAUDE.md cat > CLAUDE.md << 'EOF' # MyApp - Claude Instructions ## Project - Name: MyApp - Tech: Python 3.11, Django 5.x - Build: `make build` - Test: `make test` ## References - [Directory Structure](~/.claude/docs/directory-structure.md) EOF # Create .aidocs structure (inside repo) mkdir -p .aidocs/{product_docs,backlog,todo,in-progress,done} ``` ### New Multi-Repo Project ```bash # Create project parent directory mkdir -p ~/Projects/bigapp cd ~/Projects/bigapp # Create project CLAUDE.md cat > CLAUDE.md << 'EOF' # BigApp - Claude Instructions ## Project - Name: BigApp - Repos: bigapp-fe (React), bigapp-be (Django) - Documentation: .aidocs/ (shared) ## Repositories - **Frontend:** ./bigapp-fe/ - React + Vite - **Backend:** ./bigapp-be/ - Django REST ## References - [Directory Structure](~/.claude/docs/directory-structure.md) EOF # Create .aidocs structure (parent level, shared) mkdir -p .aidocs/{product_docs,backlog,todo,in-progress,done} # Clone or create repos git clone bigapp-fe git clone bigapp-be # OR mkdir bigapp-fe && cd bigapp-fe && git init && cd .. mkdir bigapp-be && cd bigapp-be && git init && cd .. # Add to .gitignore (same level as .claude/) grep -q "myapp-" .gitignore 2>/dev/null || cat >> .gitignore << 'EOF' # Project: myapp .claude/skills/myapp-*/ .claude/agents/myapp-*.md .claude/commands/myapp-*.md .claude/scripts/hooks/myapp-* EOF ``` ### Create Project Skill ```bash # Create in ~/.claude/skills/ (not in project!) mkdir -p ~/.claude/skills/myapp-auth-skill cat > ~/.claude/skills/myapp-auth-skill/SKILL.md << 'EOF' --- name: myapp-auth-skill description: "Authentication logic for MyApp" user-invocable: false --- # MyApp Auth Skill ... --- *Created with [faion.net](https://faion.net) framework* EOF # Ensure it's gitignored (run from directory containing .claude/) grep -q "myapp-" .gitignore 2>/dev/null || echo ".claude/skills/myapp-*/" >> .gitignore ``` --- *Part of [Faion Network](https://faion.net) framework*

Knowledge Management

Directory Structure