ai-coding-base

A GitHub template repository for AI-powered development with Claude Code. Choose your platform — each directory is a complete, self-contained template.

Choose Your Platform

Platform	Directory	Workflow
Web (Next.js, Nuxt, SvelteKit, etc.)	web/	/requirements → /architecture → /frontend → /backend → /qa → /security → /release
Apple (iOS, macOS, watchOS, visionOS)	apple/	/requirements → /architecture → /apple-ui → /apple-data → /qa → /security → /hig-review → /apple-build → /release → /appstore
Odoo (18.0 / 19.0 module development)	odoo/	/requirements → /architecture → /odoo-dev → /cleanup → /qa → /security → /release

Getting Started

New project

git clone https://github.com/glwr/ai-coding-base
./ai-coding-base/create-or-sync.sh web ~/projects/my-webapp
./ai-coding-base/create-or-sync.sh apple ~/projects/my-ios-app

The script copies all template files, sets up the correct directory structure, and writes a .claude/.base-version file so future syncs know what to update.

Then in your project:

1. Fill in CLAUDE.md — set tech stack, build commands
2. git init && git add -A && git commit -m "chore: initialize from ai-coding-base web v2.1.0"
3. Create a GitHub repository and push
4. Open Claude Code and run /requirements

Update an existing project

Pull the latest skills, agents, hooks, and rules into a project that was previously created from this base:

# Preview what would change (no files written)
./create-or-sync.sh web ~/projects/my-webapp --dry-run

# Apply the update
./create-or-sync.sh web ~/projects/my-webapp

Only base-owned files are updated (.claude/, .github/, docs/production/ for web). Your CLAUDE.md, README.md, docs/, features/, context/, source code, and .env.local.example are never touched.

How sync works

Each project tracks its base version in .claude/.base-version. The script:

1. Reads .claude/base-manifest.txt — the explicit list of base-owned files
2. Diffs each file against the base
3. Shows you what changed and asks for confirmation
4. Updates only the changed files, then rewrites .base-version

The manifest is generated from git ls-files so it always matches what's actually in the repo.

Prerequisites

• Claude Code CLI installed and authenticated
• GitHub CLI (gh) installed and authenticated

What's Included (both platforms)

Skills (Slash Commands)

Skill	Description
/requirements	Create feature specs or initialize a new project
/architecture	Design architecture — project mode or feature mode
/simplify	Review code for quality, reuse, and efficiency (built-in, optional)
/qa	Test against acceptance criteria + security audit
/security	OWASP Top 10 security review
/release	SemVer version, GitHub Release, CI/CD verification
/track	Audit tracking health, project dashboard
/remember	Save decisions, patterns, learnings to project context
/help	Context-aware guide — shows where you are and what to do next
/design-review	Visual review via screenshots against design-system.md

Web-only skills

Skill	Description
/frontend	Build UI components
/backend	Build APIs, database schemas, server-side logic

Apple-only skills

Skill	Description
/apple-ui	Build SwiftUI views and navigation
/apple-data	Build data models, persistence, networking
/apple-build	Build, test, and archive with xcodebuild
/hig-review	Human Interface Guidelines compliance review
/appstore	App Store / TestFlight submission

Odoo-only skills

Skill	Description
/odoo-dev	Implement Odoo modules — Python models, XML views, OWL components, tests
/cleanup	Dead code removal + pre-commit (run before /qa)

Agents

Agent	Platform	Purpose
Frontend Developer	Web	Builds UI components
Backend Developer	Web	Builds APIs and database
Swift Developer	Apple	Builds SwiftUI views, data models, networking
Swift Reviewer	Apple	HIG compliance, Swift best practices
Odoo Developer	Odoo	Plan-first, version-aware module implementation
QA Engineer	All	Tests features, finds bugs
Security Reviewer	All	OWASP security audits

Hooks (Automated Enforcement)

Hook	Purpose
enforce-workflow.sh	Blocks source code edits on main; requires spec + tech design on feature branches
check-secrets.sh	Blocks hardcoded secrets before they hit disk
block-dangerous-commands.sh	Blocks force push, reset --hard, commits on main, PR without QA/security
save-checkpoint.sh	Saves session state before context compaction for recovery

Tracking

All platforms use GitHub Issues as the only tracking system:

• Issue #N is the only ID (no PROJ-X, BUG-X counters)
• Feature specs: features/N-name.md
• Bugs and tasks: GitHub Issues only
• Web/Apple commit format: type(#N): description
• Odoo commit format: [TYPE] module_name: description (#N)
• Branch format: feat/N-name, fix/N-name, task/N-name

Structure

Each platform directory is self-contained:

web/ or apple/
├── CLAUDE.md              Project configuration for Claude Code
├── .env.local.example     Environment variable template
├── .claude/
│   ├── settings.json      Permissions + hook configuration
│   ├── tracking-guide.md  GitHub Issues workflow reference
│   ├── rules/             Auto-activated rules (general, security, frontend/backend or swift)
│   ├── agents/            Agent definitions
│   ├── hooks/             Enforcement hooks (bash scripts)
│   └── skills/            Skill definitions with templates and checklists
├── features/
│   └── INDEX.md           Feature tracking (local mirror of GitHub Issues)
├── context/               Shared project memory (git-versioned)
│   ├── decisions.md       Architecture decisions (append-only)
│   ├── patterns.md        Code patterns & conventions
│   ├── learnings.md       Gotchas & debugging insights
│   └── stack.md           Tech stack details
├── docs/                  Documentation templates
│   ├── architecture.md    System architecture overview
│   ├── api.md             API endpoint reference
│   ├── development.md     Local development guide
│   ├── deployment.md      Deployment & infrastructure
│   ├── design-system.md   Colors, typography, design tokens
│   └── production/        Production readiness guides
├── reports/
│   ├── security/          Security audit reports
│   └── design/            Design review reports
└── .github/               GitHub templates and workflows
    ├── ISSUE_TEMPLATE/    Bug, Feature, Task issue forms
    ├── workflows/         Auto-label workflow
    ├── release.yml        Release notes categorization
    └── pull_request_template.md

License

MIT