---
name: project-init
description: Conversational interview skill that bootstraps a project for agent-first engineering by producing lean, progressive-disclosure documentation. Use this skill when a user wants to set up CLAUDE.md, ARCHITECTURE.md, and coding standards for a new or existing project.
---

# Project Init Skill

**Version**: 1.0.0
**Category**: Project Setup
**Type**: Conversational (no script, prompt-driven)
**Session Duration**: 10-20 minutes

## Purpose

Bridge the gap between "install the SDK" and "start working on tickets." Instead of manually filling out a 300-line CLAUDE.md template, guide the user through a focused interview and generate lean, interconnected documentation that follows progressive disclosure: CLAUDE.md is a thin TOC (~80-100 lines), with details in dedicated files.

The generated documentation is optimized for agent consumption -- Claude Code reads CLAUDE.md first, then follows pointers to ARCHITECTURE.md and CODING_STANDARDS.md as needed.

## Pre-Interview: Auto-Detection

**Before asking any questions**, silently scan the working directory using Glob and Read tools. Do NOT narrate the scanning process -- just do it and use the results.

### What to Scan

- **Package manifests**: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `Gemfile`, `composer.json`, `*.csproj`
- **Existing docs**: `README.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `CODING_STANDARDS.md`
- **Config files**: `.eslintrc*`, `.prettierrc*`, `.editorconfig`, `tsconfig.json`, `tslint.json`, `biome.json`, `.rubocop.yml`, `ruff.toml`, `pyproject.toml` (tool sections), `.flake8`, `setup.cfg`
- **CI/CD**: `.github/workflows/*.yml`, `.gitlab-ci.yml`, `Dockerfile`, `docker-compose.yml`, `Jenkinsfile`
- **Directory structure**: `src/`, `lib/`, `app/`, `tests/`, `test/`, `spec/`, `docs/`, `public/`, `static/`, `components/`, `pages/`
- **Ticket database**: `.artifex/tickets.db`

### Mode Selection

Based on scan results, set mode:

- **EXISTING_PROJECT**: Found a package manifest AND source files → pre-populate answers from detected files, ask for confirmation rather than open-ended questions
- **GREENFIELD**: No package manifest or only a bare README → interview from scratch
- **ALREADY_BOOTSTRAPPED**: Found `CLAUDE.md` in the working directory → warn the user, ask whether to regenerate (overwrite), update (merge), or abort

### Flag Overrides

- `--greenfield`: Force GREENFIELD mode regardless of what's detected
- `--existing`: Force EXISTING_PROJECT mode (still scan files for pre-population)
- `--fast-track`: Skip the detailed interview and generate all four files from archetype defaults after asking only 3 essential questions (see "Fast-Track Mode" below)

### Mode Announcement

After detection, briefly tell the user what you found and which mode you're in:

> "I see this is a [TypeScript/React project with Jest testing] based on your package.json and tsconfig. I'll pre-populate what I can -- just confirm or correct as we go."

Or for greenfield:

> "This looks like a fresh start -- no project files detected. I'll walk you through setting everything up from scratch."

After announcing the mode, mention that you'll attempt an archetype classification:

> "I'll try to classify this against an archetype (saas-webapp, api-backend, marketing-site, mobile-app, internal-tool, or content-platform) so I can load sensible defaults instead of asking open questions. If I can't classify it cleanly, I'll fall back to the full interview."

## Archetype Classification

Artifex ships an archetype knowledge base at `docs/knowledge/archetypes/` (relative to the Artifex SDK installation). Each file captures a default tech stack, directory structure, key decisions, and gotchas for a common project shape. Use these files to pre-populate answers instead of interviewing from scratch.

**Available archetypes:** `saas-webapp` (multi-tenant subscription app), `api-backend` (standalone REST/GraphQL API), `marketing-site` (landing pages, waitlists), `mobile-app` (iOS/Android, Expo/RN), `internal-tool` (admin consoles, CRUD dashboards), `content-platform` (blogs, docs, CMS).

### When to Classify

- **EXISTING_PROJECT mode**: classify silently from detected files right after auto-detection, before Phase 1.
- **GREENFIELD mode**: classify after Q1 (Project Identity / Vision), once the user has described what they're building.

### Classification Heuristics

**Existing projects — detected-file signals:**

- `build.gradle.kts` + Spring Boot, no frontend dirs → `api-backend`
- `build.gradle.kts` + Spring Boot + `apps/web/` or `frontend/` → `saas-webapp`
- `package.json` with `next` + Stripe / auth libs → `saas-webapp` (confirm with user)
- `astro.config.*` with content collections → `content-platform`, else `marketing-site`
- `app.json` / `expo.json` / `ios/` + `android/` dirs → `mobile-app`
- Admin frameworks (Retool, Refine, Forest Admin, React Admin) → `internal-tool`
- FastAPI / Express / NestJS / Koa with no UI dirs → `api-backend`

**Greenfield projects — signal keywords in the Vision answer:**

- "SaaS", "subscription", "multi-tenant", "billing" → `saas-webapp`
- "API", "backend for", "microservice", "webhook" → `api-backend`
- "landing page", "waitlist", "brochure", "pre-launch" → `marketing-site`
- "iOS / Android app", "mobile app", "React Native", "Expo" → `mobile-app`
- "admin dashboard", "internal tool", "ops console", "back-office" → `internal-tool`
- "blog", "docs site", "knowledge base", "CMS" → `content-platform`

### Announce the Classification

Once you have a candidate archetype, announce it and ask the user to confirm before loading defaults:

> "Based on what you described, I'll classify this as a **saas-webapp**. Let me know if that's wrong before I load defaults — reply **OK** to continue, or name a different archetype."

If the user disagrees, either accept the archetype they name or fall back to the open-interview flow (skip "Load Archetype Defaults" and go straight to Phase 2 as written).

### Hybrid Projects

If the user describes something that spans archetypes (e.g., "a SaaS with a marketing landing page", or "an API backend plus an admin console"), identify the **primary** archetype and note the **secondary**:

- Primary = where the core business logic / value lives (usually the backend or the product surface)
- Secondary = adjunct surface (marketing site, admin console, docs)

Announce both:

> "This sounds like a **saas-webapp** primarily, with a **marketing-site** secondary. I'll load saas-webapp defaults and add an `apps/marketing/` directory alongside `apps/web/` for the landing surface."

Load defaults only from the primary archetype. Mention the secondary in the directory structure presentation but don't double-load stacks.

### Unclassifiable Projects

If after the Vision question (greenfield) or auto-detection (existing) you cannot confidently pick an archetype — e.g., the user describes something genuinely novel, or the detected stack is unusual — say so and fall back:

> "I can't cleanly classify this against a known archetype, so I'll skip the defaults and ask the detailed questions instead."

Then proceed to the standard Phase 2 open-interview flow. Never force a bad classification.

### Load Archetype Defaults

Once the archetype is confirmed, **read** `[SDK_PATH]/docs/knowledge/archetypes/<archetype>.md` with the Read tool. Extract four sections: **STACK** (Default Stack table), **STRUCTURE** (Directory Structure block), **KEY DECISIONS** (numbered decisions), and **GOTCHAS** (common gotchas — kept as a starting list, not used here).

Present stack, structure, and decisions as a single numbered list grouped by section, so the user can confirm all at once or reference item numbers to adjust:

```
Loaded defaults from docs/knowledge/archetypes/saas-webapp.md:

STACK
 1. Backend: Spring Boot 4.0.1 + Kotlin 2.3 + Java 25
 2. Database: PostgreSQL 16 + jOOQ 3.20 + Flyway
 3. Auth: Spring Security OAuth2 Resource Server (RS256 JWT)
 4. Frontend: Next.js 15 + Tailwind v4 + shadcn/ui
 5. Build: Gradle Kotlin DSL (multi-module) + pnpm (web)
 6. Deploy: Docker multi-stage (eclipse-temurin:25-alpine) + Vercel (web)

STRUCTURE
 7. Multi-module backend: api/, shared-kernel/, domain contexts
 8. apps/web/ for the Next.js frontend
 9. Contract-first OpenAPI with openapi-generator 7.12

KEY DECISIONS
10. jOOQ over JPA — explicit anti-ORM stance
11. Spring MVC (not WebFlux) for REST
12. Multi-tenant via TenantFilter + tenant_id column

Reply OK to accept all, or reference numbers to adjust (e.g., "2: use MySQL").
```

**Correction rules:**
- If the user accepts (OK), treat each item as the confirmed answer for the corresponding Phase 2 question and skip those questions.
- If the user corrects specific items, update them and re-present only the changed items.
- Known-bad combinations should be caught via `docs/knowledge/stack-compatibility.md` — if the user's override produces one, warn them and let them decide.

**Do NOT present gotchas here.** Gotchas are always interviewed (see Phase 2, question 11) — the archetype file provides a starting list that you will merge with the user's project-specific ones during the gotchas interview. **Exception:** in Fast-Track Mode, the archetype gotchas are used directly as the starting Gotchas section (see below).

## Fast-Track Mode

Fast-track is an alternative path through the skill that trades thoroughness for speed. It asks at most **3 questions**, leans entirely on archetype defaults, and generates all four files in under 2 minutes of wall-clock time. The standard interview flow is unchanged — fast-track is a separate branch the user can opt into.

### Trigger Detection

Fast-track activates in two ways:

**Explicit** — the user either:
- Invokes the skill with the `--fast-track` flag, OR
- Uses a trigger phrase like "just initialize with defaults", "skip the questions", "fast-track", "just do it", "use the defaults", "don't interview me", "bootstrap it", or any clear request to bypass the interview

When triggered explicitly, jump straight into the Fast-Track Flow below (do not run the standard Phase 1).

**Implicit** — after Phase 1 completes and archetype classification succeeds, check whether the answers so far are fully consistent with the archetype defaults:
- Archetype was classified cleanly (no ambiguity, no hybrid that needs negotiation)
- The user's Vision answer did not volunteer custom tech preferences (e.g., "but we want to use Rust instead of Kotlin", "we must use MongoDB")
- The user's Stage answer is clear
- The user has not mentioned any hard constraints that conflict with defaults

If those conditions hold, **offer** fast-track before starting Phase 2:

> "I have enough to generate everything right now using the archetype defaults. Want to skip the rest of the questions and fast-track the generation? I'll ask 3 quick questions and ship all 4 files. Reply **fast-track** to skip, or **continue** to go through the full interview."

If the user declines, proceed with the normal Phase 2 flow. If the user accepts, jump to the Fast-Track Flow (you can skip the project-name and archetype-confirmation questions since they were already answered in Phase 1).

### Fast-Track Flow

Ask **at most 3** questions. Do not stack them — ask one at a time, but keep the pace brisk. Skip any question whose answer you already have.

**Q1. Project name + one-sentence purpose** (required)
- "What's the project name, and a one-sentence description of what it does?"
- Required — you cannot generate files without this. If the user already provided it (implicit trigger from Phase 1), skip this question.

**Q2. Archetype confirmation** (only if not yet confirmed)
- "I'm classifying this as a **`<archetype>`** — correct? Reply **OK**, or name a different archetype."
- Skip if you already confirmed the archetype earlier (implicit trigger path) or if auto-detection from existing files produced a certain match.
- If the user names a different archetype, accept it and continue. If they can't pick one, see "Fast-Track Without Archetype" below.

**Q3. Hard constraints**
- "Any hard constraints I should know about? For example: must run on-prem, must use Java 21 instead of 25, must avoid AWS, must ship without a database. Reply **none** if there's nothing unusual."
- Accept **none** / **nothing** / **no** as valid answers and move on.
- If the user lists constraints, record them and apply them when loading defaults (override the conflicting stack items, note on-prem in ARCHITECTURE.md deployment section, etc.).

**That's all the questions.** Do not ask about gotchas, coding conventions, testing approach, dependencies, deployment specifics, or anything else. The archetype file already answers those.

### Load Defaults and Generate

After the 3 questions:

1. **Read exactly one file** from the knowledge base: `[SDK_PATH]/docs/knowledge/archetypes/<archetype>.md`. Extract STACK, STRUCTURE, KEY DECISIONS, and GOTCHAS. Do NOT read building-block files or any other knowledge files — fast-track trusts the archetype's choices.
2. **Apply hard constraints** from Q3 to the loaded defaults (e.g., swap the Java version, flag on-prem deployment).
3. **Generate all four files in a single pass** (CLAUDE.md, ARCHITECTURE.md, CODING_STANDARDS.md, IMPLEMENTATION_LOG.md). Do not ask for confirmation between files — write them all, then summarize.

### Fast-Track Gotchas

The Gotchas section in CLAUDE.md is populated **directly from the archetype file's GOTCHAS list** — do NOT ask the user for project-specific gotchas in fast-track mode. Use the archetype's common gotchas verbatim (or lightly adapted to the confirmed stack). This is the main deviation from the standard flow's "always interview gotchas" rule — fast-track prioritizes speed. The post-generation summary should call this out so the user knows to review and extend the section manually.

### Post-Generation Summary (Fast-Track)

After writing all four files, present a short summary:

> "Generated 4 files in fast-track mode using **`<archetype>`** defaults:
>
> - `CLAUDE.md` — project TOC with archetype gotchas
> - `ARCHITECTURE.md` — archetype structure and key decisions
> - `CODING_STANDARDS.md` — stack-appropriate conventions
> - `IMPLEMENTATION_LOG.md` — initialized with today's entry
>
> Review them and tell me if anything needs adjustment. In particular, the **Gotchas** section uses the archetype's common gotchas — you may want to add project-specific ones. If you want to redo this with the full interview, just say so and I'll run the standard flow."

Then run the normal "Post-Generation" steps (offer ticket DB init, suggest next steps).

### Fast-Track Without Archetype

Edge case: the user insists on fast-track but archetype classification failed (unclassifiable project, or the user rejected every candidate). Warn them before proceeding:

> "Fast-track works best with a clear archetype — it relies on archetype defaults for everything I'm not asking about. Without one, I'll fall back to generic defaults (saas-webapp, since it covers backend + frontend + auth + DB) which may not match your project well. Proceed anyway, or switch to the full interview?"

- **If the user confirms fast-track:** load `docs/knowledge/archetypes/saas-webapp.md` as the generic fallback, continue with Q1 and Q3 (skip Q2 since there's no archetype to confirm — you're explicitly using the fallback), generate all four files, and note in the summary that generic defaults were used. Recommend the user review ARCHITECTURE.md carefully since the structure may not fit.
- **If the user rejects fast-track:** fall back to the standard open-interview flow (Phase 1 → Phase 2 → Phase 3 → generation), exactly as described in the Interview Flow section below.

### Time Budget

Fast-track must complete in **under 2 minutes** of wall-clock time from first user message to files-on-disk. To stay under budget: read only the one archetype file, don't narrate reasoning between questions, don't re-read files in context, generate all four files in a single pass, and skip Phase 3 entirely (no pre-generation summary with correction loop — the post-generation summary is the confirmation). If you find yourself wanting a fourth question, stop — the answer is in the archetype file. Trust it.

## Interview Flow

### Phase 1: Foundation (3-4 questions)

Ask these one at a time. For EXISTING_PROJECT mode, pre-populate from detected files and ask "Is this right?" instead of open-ended questions.

> **Note on ordering with archetype classification:** For EXISTING_PROJECT mode, classification happens silently before Phase 1 begins. For GREENFIELD mode, classification happens **immediately after Q1** (the user's vision answer contains the signal keywords). After classification is announced and confirmed, proceed to the "Load Archetype Defaults" step (see the Archetype Classification section above) before Phase 2. If classification fails or the user opts out, run Phase 2 as the open interview described below.

**1. Project Identity (a.k.a. Vision)**
- Project name + one-sentence purpose
- For greenfield: this answer drives archetype classification — encourage a sentence that explains *what it is and who it's for* so the signal keywords surface
- For existing: pull name from package manifest, ask user to add the one-sentence purpose

**2. Tech Stack**
- Language, framework, database, testing framework, key tools
- For existing: "I detected [Node.js 20, Express, PostgreSQL, Jest]. Is this your core stack, or should I adjust?"

**3. Project Stage + Team**
- Early prototype / active development / mature / maintenance
- Solo developer / small team / large team
- This determines which Phase 2 questions to skip

**4. Users and Contributors**
- Who uses the software? (end users, developers, internal team)
- Who contributes to it? (just you, team members, open source)
- This shapes the documentation tone and detail level

### Phase 2: Deep Dive (5-8 questions, adaptive)

> **Fast-track skips Phase 2 entirely.** If the user triggered fast-track (explicitly via flag/phrase, or implicitly by accepting the offer after Phase 1), do NOT run Phase 2 — jump to the Fast-Track Flow's generation step. Phase 2 below is only for the standard open-interview path.

Select from these based on project stage, tech stack, and what's already detected. **Never ask more than 8 questions in Phase 2.** Skip questions where the answer is already clear from config files.

> **For classified projects:** Phase 2 shrinks dramatically. If the user accepted archetype defaults, skip questions whose answers the archetype file already provides (stack, structure, key decisions, deployment shape, formatting conventions implied by the stack). Only ask the questions below that the archetype cannot answer on its own:
>
> - **Project name** (if not already provided)
> - **Users and contributors** (Q4) — always project-specific
> - **Key dependencies** (Q7) — only the 3-5 most important beyond what's in the archetype stack
> - **Gotchas** (Q11) — **always ask**, even for classified projects (see "Preserve the gotchas exception" below)
> - Domain-specific details the user volunteered that need follow-up
>
> This typically collapses Phase 2 to 2-4 questions for classified projects. Skip everything the archetype settled.

**5. Architecture Pattern + Directory Structure**
- Monolith / microservices / serverless / monorepo / library
- Current or planned directory layout
- For existing: "Your directory structure looks like [tree]. Is this the intended architecture, or is a refactor planned?"

**6. Coding Conventions**
- Naming (functions, classes, files, constants)
- Formatting (indentation, line length, formatter tool)
- Import organization
- Comment style
- **Adapt to tech stack**: Don't ask about semicolons for Python. Don't ask about snake_case for Java. Pre-populate from detected config files (`.prettierrc`, `.eslintrc`, `ruff.toml`, etc.)
- For existing with config: "I see Prettier configured with [2-space indent, single quotes, no semicolons]. Any additional conventions not captured in config?"

**7. Key Dependencies (3-5 most important)**
- Which libraries/frameworks are central to this project and why?
- Skip for early-stage greenfield projects
- For existing: pull from manifest, ask user to highlight the 3-5 most important

**8. Testing Approach**
- Test file location and naming convention
- What framework? What needs tests?
- Minimum coverage expectations?
- How to run tests?
- For existing: detect from config and test directories

**9. Commit and Branch Conventions**
- Commit message format (conventional commits? ticket references?)
- Branch naming (feature/xxx? ticket-based?)
- PR requirements (reviews, CI checks)

**10. Deployment Setup**
- How is this deployed? (Vercel, AWS, Docker, manual, N/A)
- Any environment variables to know about?
- Skip for greenfield projects that haven't decided yet

**11. Gotchas -- THE MOST IMPORTANT QUESTION**
- "What would an AI agent get wrong about this project?"
- "What surprises new contributors?"
- "What looks obvious but has a hidden catch?"
- Chase specificity here. If the user says "the database is tricky," push: "Tricky how? Give me a specific example of something that would trip someone up."
- Spend extra time on this. The gotchas section is the most valuable part of CLAUDE.md.
- **Preserve the gotchas exception for classified projects.** Even when an archetype is loaded, STILL ask this question. The archetype file provides a starting list of common gotchas for the shape — merge those into the CLAUDE.md Gotchas section, but ask the user to add the project-specific ones on top. Present the archetype gotchas first ("Here are the usual suspects for a saas-webapp: ..."), then ask "What else is specific to *your* project that an agent would trip over?"

### Adaptive Skipping Rules

- **Archetype loaded**: Skip every question the archetype file answered (typically 5, 6, 7, 8, 9, 10). Only keep 4 (users/contributors) and 11 (gotchas), plus anything the user flagged for correction.
- **Early-stage greenfield**: Skip questions 7 (dependencies) and 10 (deployment)
- **Solo developer**: Condense question 9 (commit/branch conventions) -- just ask commit format
- **Detected config covers it**: Don't re-ask -- confirm with "I see X configured. Anything to add?"
- **User says "I don't know"**: Omit the section entirely. Never guess.

### Phase 3: Confirmation

Present a structured summary with **numbered items** so the user can efficiently confirm or correct specific entries. Each item should be verifiable at a glance.

```
PROJECT SUMMARY — Review before I generate files
==================================================

 1. Name:         [name]
 2. Purpose:      [one-liner]
 3. Stack:        [language, framework, database, testing]
 4. Stage:        [stage] | Team: [solo/team]
 5. Architecture: [pattern]
 6. Structure:    [brief layout]

 7. Naming:       [convention summary]
 8. Formatting:   [convention summary]
 9. Imports:      [organization rule]
10. Testing:      [location, framework, coverage]
11. Commits:      [format]
12. Deployment:   [summary or "Not yet decided"]

13. Key Dependencies:
    a. [lib-1]: [why]
    b. [lib-2]: [why]
    c. [lib-3]: [why]

14. Gotchas:
    a. [gotcha 1]
    b. [gotcha 2]
    c. [gotcha 3]
```

**Then ask**:

> "To confirm: reply **OK** to generate all files, or reference item numbers to correct (e.g., '3: we also use Redis' or '14a: rephrase to ...')."

**Correction rules**:
- If the user corrects items, update the summary and re-present only the changed items for final confirmation
- If the user adds new gotchas, append them and confirm
- Do NOT re-ask the full summary after minor corrections -- just confirm the changes and proceed

**Only proceed to file generation after the user explicitly approves.**

## Output File Specifications

### CLAUDE.md (~80-100 lines, NEVER exceed 120)

This is a **table of contents**, not a manual. Every section is brief and points to detailed docs.

```markdown
# CLAUDE.md

This file provides guidance to Claude Code when working with [project-name].

## Project Overview

**[project-name]**: [one-sentence purpose]

**Tech Stack**: [language] | [framework] | [database] | [testing framework]

## Project Structure

```
[project-name]/
├── [dir1]/          # [one-line description]
├── [dir2]/          # [one-line description]
├── [dir3]/          # [one-line description]
├── [config files]   # [one-line description]
└── [entry point]    # [one-line description]
```

## Artifex Directory (`.artifex/`)

Project state lives under `.artifex/`. Tracked: config, state files, lessons, evals. Untracked: tickets.db, traces, credentials, tmp/.

## Agent Efficiency Rules

- Read before writing -- always read a file before editing it
- Edit incrementally -- use targeted edits, not full file rewrites
- No redundant reads -- don't re-read files already in context
- No filler language -- be direct, skip pleasantries and summaries
- Minimal solutions -- implement what's asked, nothing more
- No unnecessary comments -- don't add comments to code you didn't change
- Prefer Edit over Write -- use Edit tool for existing files, Write only for new ones
- Compress context between phases -- compact when context grows large

## Architecture

[2-3 sentence summary of architecture pattern and key design decisions]

→ See **ARCHITECTURE.md** for component details and diagrams.

## Standards Quick Reference

- **Naming**: [one-line summary, e.g., "camelCase functions, PascalCase classes, kebab-case files"]
- **Formatting**: [one-line summary, e.g., "Prettier, 2-space indent, single quotes, no semicolons"]
- **Imports**: [one-line summary, e.g., "External first, then internal, then relative"]

→ See **CODING_STANDARDS.md** for complete conventions.

## Development Workflow

### Ticket Commands

```bash
# Get next ticket
[SDK_PATH]/skills/afx-ticket-manager/ticket-manager.sh next

# Update ticket status
[SDK_PATH]/skills/afx-ticket-manager/ticket-manager.sh update <ID> IN_PROGRESS "Starting work"

# Mark ticket done
[SDK_PATH]/skills/afx-ticket-manager/ticket-manager.sh done <ID> "Implementation complete"

# Check progress
[SDK_PATH]/skills/afx-ticket-manager/ticket-manager.sh status
```

### Implementation Flow

Follow the ticket-implementation workflow:
→ See **[SDK_PATH]/agents/afx-ticket-implementation/INSTRUCTIONS.md**

## Testing

- **Location**: [e.g., `tests/` mirroring `src/` structure]
- **Run**: `[test command]`
- **Coverage**: [e.g., "Minimum 80%, 100% for critical paths"]
- **Naming**: [e.g., "`test_<function_name>` or `<Component>.test.tsx`"]

## Key Dependencies

- **[lib-1]**: [why it's important]
- **[lib-2]**: [why it's important]
- **[lib-3]**: [why it's important]

## Gotchas

- [Specific gotcha with actionable detail]
- [Specific gotcha with actionable detail]
- [Specific gotcha with actionable detail]

## Documentation Index

| Document | Purpose |
|----------|---------|
| CLAUDE.md | This file -- quick reference and TOC |
| ARCHITECTURE.md | System design, components, patterns |
| CODING_STANDARDS.md | Naming, formatting, testing conventions |
| IMPLEMENTATION_LOG.md | Chronological log of ticket implementations |
```

**Rules for CLAUDE.md**:
- Count your lines. If approaching 100, cut aggressively. Never exceed 120.
- No placeholder brackets `[like this]` in the final output. Every value must be filled from interview answers or omitted entirely.
- Use `→ See **FILE.md**` pointers liberally to keep this file thin.
- The Gotchas section should have 3-7 specific, actionable bullets. This is the highest-value section.
- Replace `[SDK_PATH]` with the actual absolute path to the Artifex installation.

### ARCHITECTURE.md (~100-200 lines)

Lean skeleton -- enough to orient an agent, not a full design document.

```markdown
# Architecture

## System Overview

[Project name] is a [type of system] that [primary purpose].

[2-3 sentences on high-level architecture choices and why they were made]

## High-Level Diagram

```
[ASCII diagram showing major components and data flow]
[Keep it simple: boxes and arrows, max 15 lines]
```

## Component Architecture

### [Component 1]
- **Location**: `[directory/]`
- **Purpose**: [what it does]
- **Key files**: [2-3 most important files]
- **Depends on**: [other components]

### [Component 2]
[Same structure, repeat for 3-7 components]

## Design Patterns

### [Pattern Name]
- **Where**: [which components use it]
- **Why**: [why this pattern was chosen]
- **Example**: [file reference]

[Only include patterns actually mentioned in the interview]

## Data Architecture

[Only include if database was mentioned]

- **Database**: [type and name]
- **Key entities**: [list main tables/collections]
- **Relationships**: [brief description]

## Development Guidelines

- Follow ticket-based workflow (see CLAUDE.md → Development Workflow)
- Log implementations in IMPLEMENTATION_LOG.md
- Follow conventions in CODING_STANDARDS.md
```

**Rules for ARCHITECTURE.md**:
- For greenfield projects: mark sections as "(planned)" where design isn't finalized
- For existing projects: populate from actual code structure
- No placeholder brackets in final output
- Skip sections that don't apply (e.g., no Data Architecture if no database)

### CODING_STANDARDS.md (~60-120 lines)

```markdown
# Coding Standards

Standards and conventions for [project-name].

## Naming Conventions

| Element | Convention | Example |
|---------|-----------|---------|
| Functions | [convention] | `[example]` |
| Classes | [convention] | `[example]` |
| Constants | [convention] | `[example]` |
| Files | [convention] | `[example]` |
| Variables | [convention] | `[example]` |

## Formatting

- **Indentation**: [e.g., 2 spaces]
- **Line length**: [e.g., 80 characters]
- **Formatter**: [e.g., Prettier -- see `.prettierrc`]
- **Quotes**: [e.g., single quotes]
- **Semicolons**: [e.g., no semicolons]
- **Trailing commas**: [e.g., ES5]

[For existing projects with config files: "See `[config file]` for full configuration. Key overrides:"]

## Import Organization

[Order and grouping rules, e.g.:]
1. Standard library / built-in modules
2. External packages
3. Internal modules (absolute paths)
4. Relative imports
5. Type imports (if applicable)

## Comments

- [Style guide, e.g., "Explain WHY, not WHAT"]
- [Documentation format, e.g., "JSDoc for public functions"]
- [When NOT to comment, e.g., "No obvious comments like // increment counter"]

## Error Handling

- [Approach, e.g., "Use custom error classes extending AppError"]
- [Logging, e.g., "Log at error boundary, not at throw site"]
- [User-facing, e.g., "Never expose stack traces to users"]

## Testing Conventions

- **Location**: [e.g., `tests/` directory mirroring `src/`]
- **Naming**: [e.g., `test_<function>.py` or `<Component>.test.tsx`]
- **Structure**: [e.g., "Arrange-Act-Assert pattern"]
- **What needs tests**: [e.g., "All business logic, API endpoints, edge cases"]
- **What doesn't**: [e.g., "Pure configuration, simple type definitions"]

## Git Conventions

### Commit Messages

```
[format, e.g.:]
<type>: <summary>

Implements: Ticket <ID>
```

Types: [e.g., feat, fix, refactor, test, docs, chore]

### Branches

[e.g., `feature/<ticket-id>-short-description`, `fix/<ticket-id>-short-description`]

### Pull Requests

[e.g., "Require 1 review, all CI checks passing"]
```

**Rules for CODING_STANDARDS.md**:
- For existing projects with config files: reference the config rather than duplicating. "See `.prettierrc` for formatting. Key overrides: [list only non-default values]"
- Adapt to tech stack: don't include irrelevant sections (no semicolons section for Python, no snake_case section for JavaScript)
- No placeholder brackets in final output
- If user said "I don't know" for a section, omit it entirely

### IMPLEMENTATION_LOG.md

Generate from the SDK template with the "Template Instructions" section removed and an initialization entry added:

```markdown
# Implementation Log

Lean chronological log of ticket implementations.

**Format**: Date, Ticket ID, one-line summary, files changed.

---

## [TODAY'S DATE] Project Initialization
Bootstrapped project documentation via project-init skill.
Files: CLAUDE.md, ARCHITECTURE.md, CODING_STANDARDS.md, IMPLEMENTATION_LOG.md
```

Use today's actual date.

## Post-Generation

### Offer Ticket Database Initialization

After generating files, check if `.artifex/tickets.db` exists in the working directory:
- If NOT present: "Would you like me to initialize the ticket database? I'll run `ticket-manager.sh init`."
- If present: Skip this offer.
- If yes: Execute the init command.

### Next Steps Recommendation

Close with specific, actionable next steps:

> "Your project is bootstrapped. Here's what I'd suggest next:
>
> 1. **Review the generated files** -- especially the Gotchas section in CLAUDE.md. Tweak anything that doesn't feel right.
> 2. **[If existing project]** Run the architecture-documentation agent for a deeper analysis of your codebase.
> 3. **[If they have requirements]** Import your project plan with `/afx-requirements-converter` and then `/afx-init-tickets`.
> 4. **Start building** -- use `/afx-next-ticket` to grab your first ticket."

## Interview Rules

1. **One question at a time.** Never stack multiple questions. Let the user think.

2. **Pre-populate, don't interrogate.** For existing projects, show what you detected and ask for confirmation. Don't make the user repeat information that's already in their config files.

3. **Adapt to tech stack.** Don't ask about semicolons for Python projects. Don't ask about snake_case for Java projects. The questions should feel relevant to what the user is building.

4. **Skip what doesn't apply.** Early-stage projects don't have deployment. Solo developers don't need PR review rules. If it doesn't apply yet, don't ask.

5. **Chase specificity on gotchas.** This is the one place to push. If the user gives a vague gotcha, ask for a concrete example. "The database is weird" → "Weird how? What would trip up an AI agent specifically?"

6. **No file generation during the interview.** Don't write any files until Phase 3 confirmation is approved. The interview and the generation are separate phases.

7. **Respect "I don't know."** If the user doesn't know or hasn't decided, omit the section entirely. An empty section is better than a guessed one.

8. **Keep it under 20 minutes.** The entire interview should feel brisk. Don't belabor obvious answers. If detection handles most of it, the interview might be 5 minutes.

9. **No placeholder brackets in output.** Every `[value]` in the templates above must be replaced with real content or the section must be omitted. Never generate a file with `[TODO]` or `[fill this in]`.

10. **Be warm but efficient.** This is a project setup, not a therapy session. Friendly, professional, moving forward.

## Session Start

When the skill is invoked, begin with:

1. **Check for explicit fast-track trigger** — if the invocation includes `--fast-track` or the user's message contains a fast-track phrase ("just initialize with defaults", "skip the questions", "fast-track", "just do it", "use defaults", "don't interview me", "bootstrap it"), set a fast-track flag and skip the "10-20 minutes" welcome in favor of a brief "fast-track acknowledged" message.
2. **Brief welcome** that sets expectations (standard path: 10-20 minutes, 4 files; fast-track path: under 2 minutes, 4 files, 3 questions)
3. **Run auto-detection** silently (unless flag overrides)
4. **Announce mode** and what was detected
5. **Attempt archetype classification**:
   - Existing projects: classify silently from detected files, then announce the candidate archetype before Phase 1
   - Greenfield projects: defer classification until after Q1 (Vision) — unless fast-track is already active, in which case Q1 of the Fast-Track Flow will capture the vision and classification together
6. **Branch on fast-track state**:
   - **Explicit fast-track** → jump to the Fast-Track Flow (ask Q1–Q3, generate)
   - **No fast-track yet** → launch into Phase 1, Question 1. After Phase 1 completes and archetype classification succeeds cleanly, consider offering **implicit** fast-track before starting Phase 2.

**Example opening (explicit fast-track)**:

> Fast-track mode — I'll ask 3 quick questions and generate all 4 files from archetype defaults. No deep interview.
>
> First: **What's the project name, and a one-sentence description of what it does?**

**Example opening (existing project)**:

> Let me take a quick look at your project...
>
> OK, I can see this is a TypeScript/React project using Next.js, with Jest for testing and Prettier for formatting. Based on the Stripe SDK and Auth0 wiring I'm also seeing, I'll classify this as a **saas-webapp** and load defaults from the archetype knowledge base — reply **OK** if that's right, or name a different archetype.

**Example opening (greenfield)**:

> Let me check what we're working with...
>
> Looks like a fresh start -- no project files detected. I'll walk you through everything from scratch. This should take about 15 minutes, and at the end you'll have CLAUDE.md, ARCHITECTURE.md, CODING_STANDARDS.md, and an implementation log ready to go. Once you tell me what you're building, I'll try to match it against an archetype so we can skip the obvious questions.
>
> First up: **What's the project name and a one-sentence description of what it does?**

## When NOT to Use This Skill

- When the user already has a well-maintained CLAUDE.md they're happy with
- When the user wants deep codebase analysis (use the architecture-documentation agent instead)
- When the user just wants to set up tickets without documentation (use `/afx-init-tickets`)
- When the project is a one-off script that doesn't need documentation