Ai native foundation

AI Native Foundation - Setup Skill

This skill installs the "Junior dev + PM × AI Senior Tech Lead" framework into the user's Claude Code setup. It can do a fresh install or augment an existing setup.

Important: This skill writes to the user's ~/.claude/ directory. If files exist, it does NOT OVERWRITE - it backs them up and offers a merge. The user approves at every step.

---

What the skill does (in order)

Step 0 - Environment check

• Is Claude Code installed? (which claude)
• Does ~/.claude/ exist?
• Detect existing files: ~/.claude/CLAUDE.md, ~/.claude/hooks/*, ~/.claude/skills/*, ~/.claude/settings.json

If existing files are found, ask:

"Detected an existing setup. Found: [list]. Should I back up and add alongside (recommended), or review and merge manually?"

Step 1 - User information

Questions (one per turn):

1. Your name? (for {{user_name}} placeholder replacement)
2. Closest role? Multiple choice:
   • A) Junior dev + PM hybrid
   • B) Solo founder / multi-front
   • C) Senior dev + AI as power tool
   • D) Other (free text)
3. Active project(s)? (for multi-project routing)
   • Project name + directory + type
4. Are you using or planning to use Obsidian Vault? (yes/no/later)

(Note: no "areas" question - all 9 architectural skills are installed by default; they're stack-agnostic patterns.)

Step 2 - CLAUDE.md install

Copy templates/CLAUDE.md to ~/.claude/CLAUDE.md. Replace placeholders:

• {{user_name}} → user's name
• {{primary_role}} → selected role
• Multi-project routing table: fill from user's project info

If the file exists: backup (~/.claude/CLAUDE.md.backup-YYYY-MM-DD), write the new one, present a merge strategy.

Step 3 - Hooks install

templates/hooks/* → ~/.claude/hooks/. Then:

chmod +x ~/.claude/hooks/pre_tool_use.sh
chmod +x ~/.claude/hooks/post_tool_use.sh
chmod +x ~/.claude/hooks/test_suite.sh

Run the test suite:

~/.claude/hooks/test_suite.sh

If the test suite passes → continue. If it reports issues → show logs to the user and propose a fix.

Step 4 - settings.json install

Copy templates/settings.json to ~/.claude/settings.json. If existing: don't delete - JSON merge.

Critical block:

"hooks": {
  "PreToolUse": [
    {"matcher": "Bash", "hooks": [{"type": "command", "command": "~/.claude/hooks/pre_tool_use.sh"}]}
  ]
}

Step 5 - SENIOR-TRAPS.md install

Copy examples/senior-traps.md to ~/.claude/SENIOR-TRAPS.md.

Tell the user:

"This is a sample architectural trap catalog. Add traps you encounter (cross-project lesson transfer). Format in docs/customization.md."

Step 6 - Skills install (all 9 by default)

Architectural skills are stack-agnostic patterns; install all of them:

mkdir -p ~/.claude/skills
cp examples/skills/framing-product-decisions.md ~/.claude/skills/
cp examples/skills/categorizing-decisions.md ~/.claude/skills/
cp examples/skills/collaborating-with-ai-agent.md ~/.claude/skills/
cp examples/skills/designing-webhook-handlers.md ~/.claude/skills/
cp examples/skills/coordinating-multi-source-identity.md ~/.claude/skills/
cp examples/skills/designing-atomic-transactions.md ~/.claude/skills/
cp examples/skills/defending-in-depth.md ~/.claude/skills/
cp examples/skills/recording-decisions-to-evolution-log.md ~/.claude/skills/
cp examples/skills/adding-trap-to-catalog.md ~/.claude/skills/

Tell the user:

"These 9 architectural skills install by default. They cover product framing, decision categorization, AI collaboration, three implementation domains (webhooks, identity, transactions), 5-layer code review (defending-in-depth), and two memory-hygiene skills (recording-decisions-to-evolution-log + adding-trap-to-catalog) that auto-write to your working-style.md and trap catalog. All stack-agnostic. Skill authoring guide: templates/skills/README.md."

Step 7 - Working Style manifesto install

Copy templates/working-style.md into the user's project directory (default: <cwd>/docs/working-style.md).

Replace placeholders + tell the user:

"This manifesto is a living doc - anything that changes in the system should also be updated here. Use the Evolution log to read decisions back."

Step 8 - Memory system

Memory is automatic. Claude Code creates session-based memory in ~/.claude/projects/<cwd-encoded>/memory/. Explain:

"Memory is automatic - built on Claude Code's native cross-session memory. Decisions, feedback, project state from new sessions persist in the background. No manual intervention - only when you say 'remember this'."

Step 9 - Obsidian Vault install (optional)

If the user said yes:

• Copy templates/obsidian-CLAUDE.md to the vault root
• Suggest the folder skeleton: 01-Projects/, 02-Areas/, 03-Resources/, 04-Archive/, _MOC/, raw/
• Explain the AUTO-WRITE trigger table

Detail: docs/obsidian-setup.md.

Step 10 - Verification

Ask the user a test question:

"Now open a new terminal, start Claude Code, and write: 'Let's brainstorm a new feature: pushing notifications to users.' If the framework installed correctly, Claude should auto-invoke superpowers:brainstorming."

If the test fails: troubleshoot (CLAUDE.md auto-trigger patterns, plugin enable check).

Step 11 - Final summary

✅ AI Native Foundation installed

Loaded:
- ~/.claude/CLAUDE.md (operational rules)
- ~/.claude/SENIOR-TRAPS.md (sample architectural trap catalog)
- ~/.claude/skills/ (9 architectural skills)
- ~/.claude/hooks/ (security guardrails, test suite ran)
- ~/.claude/settings.json (permissions + hook reg)
- <cwd>/docs/working-style.md (manifesto)
- [obsidian setup if selected]

Next steps:
1. Read `docs/philosophy.md` - why this framework
2. Read `docs/customization.md` - how to tune the rules
3. Start your first task - framework is active

Issues: GitHub issues

---

Skill behavior notes

Conversation style

Match the user's language and tone. Default English; if the user writes in another language, follow.

Asking for approval

Before each file write, present summary + ask:

"~/.claude/CLAUDE.md will be written - operational rules, ~10KB. Existing file will be backed up. Continue?"

Error handling

On Bash errors:

• Permission denied → suggest chmod
• File exists → propose backup
• jq not installed (hook dependency) → suggest brew install

Existing system protection

Never delete. Always backup and write alongside. The user decides via manual review.

---

Side resources

After the skill finishes, redirect the user to:

• docs/philosophy.md - philosophy
• docs/decision-types.md - 🔴/🟡/🟢 system
• docs/customization.md - tune
• docs/obsidian-setup.md - vault detail
• examples/skills/* - architectural skills
• examples/senior-traps.md - trap catalog

This skill runs once. After install, return to normal Claude Code flow.