folder-architect

Files (1)

• SKILL.md

SKILL.md (first lines)

# folder-architect

Designs and audits project folder structures, grounded in the Team Knowledge Base.

| Command / phrase | Mode | What it does |
|---|---|---|
| `/setup-folder`, "set up a new project", "design my folder structure" | **Bootstrap** | Asks ~3 questions about project intent → drafts structure citing KB → creates folders + stub `CLAUDE.md` / `CONTEXT.md` files on approval |
| `/organize-folder`, "review my folder", "audit my project structure" | **Audit** | Reads current state → checks against 7 mistakes → proposes restructuring plan → executes file moves on explicit approval |

**Scope v1:** code projects only (Python, JS/TS, Rust, Go — detected by language markers). Obsidian vaults, content workspaces, client-delivery projects are out of scope this version.

**Authority:** plan-then-execute. Skill never moves files without explicit "yes execute" after showing the plan.

**Citations mandatory:** every structural recommendation links to the KB note it draws from. If there's no KB source for a recommendation, the skill doesn't make it.

---

## Step 1 — Locate the Team Knowledge Base

The skill's grounding lives in `Team Knowledge Base/wiki/`. Find it by walking up from `cwd` looking for `Team Knowledge Base/AGENTS.md` as the marker file.

```
Start at cwd. Check for "Team Knowledge Base/AGENTS.md" in cwd, parent, grandparent,
up to 5 levels. First hit wins. Set $KB to that directory.
```

If not found in any ancestor → ask the user where the KB lives. Don't proceed without it.

On the user's machine the KB lives at `Workspace/Team Knowledge Base/`, so the walk-up succeeds for any project under `Workspace/`.

---

## Step 2 — Detect mode

- User typed `/setup-folder` or said "set up a new project" / "design my folder structure" / "bootstrap a new project" → **Bootstrap mode** (Step 3)
- User typed `/organize-folder` or said "review my folder" / "audit my project structure" / "is this organized well" → **Audit mode** (Step 4)

If ambiguous, ask which mode in one question.

---

## Step 3 — Bootstrap mode

### 3a. Read the ground-truth KB notes (always)

Always read these before doing anything else:

- `$KB/wiki/patterns/folder-architecture-mistakes.md` — the 7 anti-patterns to avoid
- `$KB/wiki/workflows/code-project-workspace-starter.md` — the canonical code-project structure
- `$KB/wiki/patterns/three-layer-context-architecture.md` — Map → Rooms → Tools

These are the spine. Every recommendation builds on them.

### 3b. Ask ~3 targeted questions

In one message, not iteratively:

1. **What is this project?** (one or two sentences — what it does, who uses it)
2. **What language(s)?** (Python, JS/TS, Rust, Go, mixed)
3. **What "modes of work" does it have?** (the KB's mistake #3: don't make workspaces for file *categories*; make them for *mental modes*. Example: planning is different from coding is different from ops. Each gets its own workspace.)

Optional 4th if not obvious from cwd context: **Is this a fresh empty folder, or will the skill be writing into an existing directory?**

### 3c. Read opportunistic KB notes based on answers

Add reads only if relevant:

- If the project needs structured decision-tracking → also read `$KB/wiki/patterns/queryable-organization.md` and `$KB/wiki/patterns/externalized-workspace-state.md`
- If the project is agent-facing (Claude Code / MCP / etc.) → also read `$KB/wiki/concepts/agent-native-workspace.md`
- If the project will be shared with collaborators → also read `$KB/wiki/patterns/handoff-ready-workspace.md` if it exists

### 3d. Detect the user's existing decision-log convention

If `~/.claude/skills/decision-log/SKILL.md` exists, the user has the decision-log skill installed. That skill uses `docs/STATUS.md` + `docs/decisions/` + `docs/log/`. **In bootstrap mode, recommend this structure instead of the KB's `planning/decisions/`** — the user's installed convention wins over the KB's general suggestion. Cite both: "The KB's canonical structure has `planning/decisions/` ([[code-project-workspace-starter]]); you also have the decision-log skill installed which uses `docs/decisions/`. Going with the installed convention."

### 3e. Draft the structure

Output a tree like this (concrete file/folder list), with a parallel **"why each part"** section that cites KB notes:

```
<project-name>/
├── CLAUDE.md              # Layer 1 root map per [[three-layer-context-architecture]]
├── README.md              # human-facing setup + overview
├── pyproject.toml         # (for Python; if JS, package.json; etc.)
├── .env.example
├── .gitignore
├── src/
│   ├── CONTEXT.md         # Layer 2 workspace context per [[three-layer-context-architecture]]
│   └── <package>/
├── tests/
├── docs/
│   ├── CONTEXT.md         # Layer 2 workspace context
│   ├── STATUS.md          # per decision-log skill (if installed)
│   ├── decisions/         # ADRs; see [[code-project-workspace-starter]] (KB has them in planning/decisions/; using docs/ for decision-log compatibility)
│   └── log/               # session logs per decision-log skill (if installed)
├── scripts/               # ops/scripts per [[code-project-workspace-starter]]
└── output/ or data/       # if the project produces artifacts
```

Adjust the tree based on the user's project. If they don't need `scripts/`, drop it. If they have a data corpus, include `output/` or `data/`. Don't fabricate folders the user didn't ask for.

**Cite the KB inline.** Every folder gets a one-line "why" with a `[[wikilink]]` to the source KB note.

### 3f. Show draft + wait for approval

```
---
Proposed structure for <project-name>:

[tree]

Reasoning (KB-grounded):
- CLAUDE.md (root) — [[three-layer-context-architecture]] Layer 1: routing file, <40 lines max ([[folder-architecture-mistakes]] #1)
- src/CONTEXT.md — Layer 2 workspace context
- docs/decisions/ — ADRs (matches your installed decision-log skill; KB canonical is planning/decisions/)
- (etc., one bullet per folder)

Files I'll create (just stubs + the folders themselves):
- CLAUDE.md          ~30 lines of stub

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness