SimpleApps project conventions for directory layout, .claude integration, permission defaults, and .simpleapps/ configuration. Load when setting up projects, checking structure, or configuring Claude Code defaults.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
SimpleApps project conventions for directory layout, .claude integration, permission defaults, and .simpleapps/ configuration. Load when setting up projects, checking structure, or configuring Claude Code defaults.
allowed-tools
["Read","Bash"]
user-invocable
false
Project Defaults
Base Directory Standard
All projects live under ~/projects/ in two groups:
Workspace files go in ~/projects/workspaces/, one .code-workspace per project
macOS APFS is case-insensitive by default. ~/Projects/ and ~/projects/ resolve to the same directory. Do NOT flag path casing differences as errors. Only flag paths that genuinely do not resolve.
Project Directory Layout
Every project MUST use this layout:
{project}/
โโโ CLAUDE.md # โ repo/.claude/CLAUDE.md
โโโ .claude/ # Claude Code config (symlinks to repo/.claude/)
โ โโโ settings.json # โ repo/.claude/settings.json
โ โโโ settings.local.json # Machine-local, gitignored, NOT symlinked
โ โโโ rules/ # โ repo/.claude/rules/
โ โโโ commands/ # โ repo/.claude/commands/
โ โโโ prompts/ # โ repo/.claude/prompts/
โ โโโ hooks/ # โ repo/.claude/hooks/
โโโ repo/ # Git repo (simpleapps-com/<name>.git)
โโโ wiki/ # Wiki repo (simpleapps-com/<name>.wiki.git)
โโโ goals/ # Active goal tracking (not in git)
โโโ wip/ # Work-in-progress files (not in git)
โโโ tmp/ # Temporary files (not in git)
โโโ .simpleapps/ # Config, credentials, site profile (not in git)
The parent {project}/ is NOT a git repo. It keeps code and wiki side-by-side. The git repo is always at repo/. Use git -C repo for git operations from the project root.
Content
Location
Examples
Product code
repo/
Source, tests, configs, SKILL.md files
Dev documentation
wiki/
Architecture, guides, specs, conventions
Repo .claude/rules/
repo/
Minimal summaries referencing wiki
Repo .claude/CLAUDE.md
repo/
Quick reference + wiki links
Active goals
goals/
Current cycle/sprint objectives being tracked
Active task context
wip/
{issue-number}-{short-desc}.md files
Temporary files
tmp/
Scratch space: commit msgs, PR bodies, intermediate output. Full access.
SimpleApps config
.simpleapps/
Settings, site profile, credentials (see below)
goals/: Project-level scratch space (sibling of repo/) for the goals/objectives currently being worked. Short-lived: reviewed regularly, archived or deleted when the goal is met, like wip/ but goal-scoped rather than task-scoped. Not in git; lives on one machine. MUST NOT hold durable team-shared goals (those go in wiki/) or secrets.
WIP: Research, plans, decisions, test results. MUST NOT contain secrets, final docs, or code. See simpleapps:wip for the frontmatter schema, status lifecycle, retention rule, and daily processing via /process-wips.
tmp/: Project-level scratch space (sibling of repo/) for commit messages, PR/issue bodies, intermediate output, and throwaway files. Read, write, and delete freely without asking; create the folder if missing; clean up after use.
MUST keep scratch files in the project-leveltmp/, NEVER repo/tmp/ (or wiki/tmp/). Files inside a git tree get swept into commits by git add -A/git add .; a real incident put tmp/commit-msg.txt onto a project's main branch this way. Add tmp/ to each repo's .gitignore as a safety net, but the convention is to stay outside the tree entirely so the accident cannot recur.
Standard patterns. Note the ../tmp/ indirection: git -C repo / git -C wiki resolves -F and other paths relative to that subdir, so a plain tmp/ would wrongly mean repo/tmp/:
See simpleapps:github for the full git/gh command conventions.
Plugin Rules
The plugin ships rule templates in plugins/simpleapps/rules/ that MUST exist in every project's repo/.claude/rules/. Rules are always loaded into context. They enforce baseline guardrails (like git safety) without depending on a skill being invoked. The /project-init command copies missing rules from the plugin into the project.
Resolution: read {project}/.simpleapps/settings.json first, fall back to ~/.simpleapps/settings.json, fall back to defaults. Field-level override: project wins for any field it defines.
.simpleapps/ is gitignored and lives on one machine. MUST NOT store anything here that the team needs to share, anything that should travel with the repo (e.g., wiki token budget overrides; those go in wiki/Home.md as HTML comments), or anything that MUST be reproducible on a fresh clone.
site.json
One per client project. Consistent structure across all sites: same fields, different values. Replaces the old {siteId}.json pattern.
MUST NOT commit .simpleapps/ to git. Contains PII and credentials.
MUST NOT save site data to wiki or memory (PII)
MUST NOT create {siteId}.json files. Use site.json instead.
If old {siteId}.json files exist, /project-init will flag them for migration to site.json
Resolution order
{project}/.simpleapps/settings.json is read first, then falls back to ~/.simpleapps/settings.json. Project-level fields override user-level ones.
.claude/settings.local.json
This file SHOULD be gitignored. It contains project-specific settings that are machine-local and should not be committed.
Symlink Setup
Six symlinks let you run Claude Code from {project}/ and still get the repo's memory, settings, rules, commands, prompts, and hooks loaded automatically:
Symlink
Target
Purpose
{project}/CLAUDE.md
repo/.claude/CLAUDE.md
Project memory loaded at session start
{project}/.claude/settings.json
repo/.claude/settings.json
Shared, committed project settings
{project}/.claude/rules
repo/.claude/rules
Always-loaded rule files
{project}/.claude/commands
repo/.claude/commands
Slash commands
{project}/.claude/prompts
repo/.claude/prompts
Reusable prompt files
{project}/.claude/hooks
repo/.claude/hooks
Hook scripts
The canonical files live in repo/.claude/ so they travel with the repo and are version-controlled. The symlinks make them visible from the parent {project}/ working directory. CLAUDE.md symlinks to the project root (not inside .claude/) because Claude Code loads project memory from {project}/CLAUDE.md.
.claude/settings.local.json is NOT symlinked. It is machine-local, gitignored, and stays directly in {project}/.claude/. See .claude/settings.local.json below.
/project-init creates and repairs all six.
Permission Defaults
Every project SHOULD configure .claude/settings.local.json with these rules. env and permissions are honoured at project scope; autoMode is NOT (see below):
cd - Use git -C repo instead; compound cd && git triggers unblockable prompts
kill/pkill - Use TaskStop to manage background tasks
Edit(~/.claude/plugins/**) / Write(~/.claude/plugins/**) - Plugin tree is a cache; edit source repo instead
Auto Mode Guardrail (user settings only)
autoMode MUST live in ~/.claude/settings.json, not in any project settings file. Claude Code reads autoMode from user settings, the --settings flag, and managed settings only; it is ignored in project .claude/settings.json and .claude/settings.local.json. A hard_deny written into a project file looks correct in review and silently protects nothing.
{"autoMode":{"hard_deny":["Bash(git push:*)"]}}
hard_deny blocks the auto-mode classifier from approving git push regardless of user intent or allow exceptions, which is what makes the simpleapps:git-safety guardrail (explicit user approval per push) enforceable in auto mode. Manual approval at the prompt still works.
autoMode also accepts environment, allow, and soft_deny arrays. Include the literal string "$defaults" in an array to inherit the built-in rules at that position.
Bin Scripts (PATH)
The augur-skills plugin includes shell scripts (cld, cldo, tmcld, etc.) in plugins/simpleapps/bin/. When installed via the Claude Code marketplace, these live at:
# SimpleApps augur-skills bin scriptsexport PATH="$PATH:$HOME/.claude/plugins/marketplaces/augur-skills/plugins/simpleapps/bin"
This path is stable across plugin updates (marketplace updates are git pulls). The project-init command checks for this and adds it if missing.
New Project Setup
Use /project-init to set up a new project. This command verifies the directory structure, syncs plugin rules, and configures permissions automatically.
For manual setup (advanced), see the wiki for the complete setup procedure.
