ai-coding-starter-kit/.claude/rules/general.md

General Project Rules

New Project Detection (MANDATORY)

Before starting ANY work, check if the project has been initialized:

1. Read docs/PRD.md - if it still contains placeholder text like "Describe what you are building", the project is NOT initialized
2. Read features/INDEX.md - if the features table is empty, no features have been defined

If the project is not initialized:

• Do NOT write any code or create any components
• Do NOT skip ahead to implementation
• Instead, tell the user: "This project hasn't been set up yet. Let's start by defining what you want to build. Run /requirements with a description of your idea (e.g. /requirements I want to build a task management app)."
• If the user already described their idea in the current message, run /requirements automatically with their description

If the project is initialized but the user requests a feature not yet in INDEX.md:

• Guide them to run /requirements first to create the feature spec before any implementation

Feature Tracking

• All features are tracked in features/INDEX.md - read it before starting any work
• Feature specs live in features/PROJ-X-feature-name.md
• Feature IDs are sequential: check INDEX.md for the next available number
• One feature per spec file (Single Responsibility)
• Never combine multiple independent functionalities in one spec

Git Conventions

• Commit format: type(PROJ-X): description
• Types: feat, fix, refactor, test, docs, deploy, chore
• Check existing features before creating new ones: ls features/ | grep PROJ-
• Check existing components before building: git ls-files src/components/
• Check existing APIs before building: git ls-files src/app/api/

Human-in-the-Loop

• Always ask for user approval before finalizing deliverables
• Present options using clear choices rather than open-ended questions
• Never proceed to the next workflow phase without user confirmation

Status Updates (MANDATORY - Write-Then-Verify)

After completing work on any feature, you MUST update tracking files. Follow this exact sequence:

1. Read the feature spec (features/PROJ-X-*.md) and features/INDEX.md BEFORE editing
2. Write your changes using the Edit tool — do NOT just describe what you would write
3. Re-read the file AFTER editing to verify the changes are actually present
4. If changes are missing, repeat step 2 — never claim updates were made without verifying

What to update in the feature spec:

• Status field in the header (Planned → In Progress → In Review → Deployed)
• Implementation notes: what was built, what changed, any deviations from the original spec
• Bug fixes or design changes discovered during implementation

What to update in features/INDEX.md:

• Feature status column must match the feature spec header
• Valid statuses: Planned, In Progress, In Review, Deployed

NEVER do this:

• Do NOT say "I've updated the feature spec" without actually calling the Edit tool
• Do NOT summarize changes in chat as a substitute for writing them to the file
• Do NOT skip updates because "it's obvious" or "minor"

File Handling

• ALWAYS read a file before modifying it - never assume contents from memory
• After context compaction, re-read files before continuing work
• When unsure about current project state, read features/INDEX.md first
• Run git diff to verify what has already been changed in this session
• Never guess at import paths, component names, or API routes - verify by reading

Handoffs Between Skills

• After completing a skill, suggest the next skill to the user
• Format: "Next step: Run /skillname to [action]"
• Handoffs are always user-initiated, never automatic