Forge Setup Project

Set Up Project Meta-Structure

Set up a project's meta-structure for agentic engineering — the foundational files that make a codebase navigable and maintainable by both humans and AI agents.

Input

Optional: A path to the project root: $ARGUMENTS

If no argument is provided, use the current working directory.

Process

Step 1: Determine Project State

Scan the project root to classify what exists:

# Check for existing meta files
ls -la CLAUDE.md AGENTS.md README.md CHANGELOG.md .claude/settings.local.json 2>/dev/null

# Check for docs directory
ls docs/ 2>/dev/null

# Check for any code at all
ls -la

Classify the project into one of four states:

If existing meta files are found, use AskUserQuestion to ask:

• Which files to overwrite vs. keep
• Whether to merge content (for README.md especially)

Step 2: Explore the Codebase

Skip this step for greenfield projects.

For existing projects, perform a thorough exploration:

# Directory structure (top 3 levels)
find . -maxdepth 3 -type f -not -path './.git/*' -not -path './node_modules/*' -not -path './vendor/*' -not -path './.next/*' -not -path './dist/*' -not -path './build/*' | head -100

# Detect language/runtime
ls package.json go.mod Cargo.toml pyproject.toml setup.py Gemfile build.gradle pom.xml mix.exs deno.json bunfig.toml composer.json 2>/dev/null

# Package manager and scripts
cat package.json 2>/dev/null | head -80
cat Makefile 2>/dev/null | head -80
cat Taskfile.yml 2>/dev/null | head -80

# Entry points
ls -la src/ app/ cmd/ lib/ main.* index.* 2>/dev/null

# CI/CD configuration
ls .github/workflows/*.yml .gitlab-ci.yml Jenkinsfile .circleci/config.yml 2>/dev/null

# Lint/format configuration
ls .eslintrc* biome.json .prettierrc* .golangci.yml rustfmt.toml .rubocop.yml pyproject.toml 2>/dev/null

# Test configuration
ls jest.config* vitest.config* pytest.ini .mocharc* 2>/dev/null

# Docker
ls Dockerfile docker-compose*.yml 2>/dev/null

# Existing documentation
ls docs/*.md *.md 2>/dev/null

Record what you discover:

• Language(s) and runtime
• Package manager
• Available scripts/make targets (build, test, lint, format, dev, etc.)
• Project structure pattern (monorepo, single app, CLI tool, library, etc.)
• Test framework
• CI/CD setup
• Entry points and architecture style

Step 3: Gather Project Information

Use AskUserQuestion to collect what can't be determined from code:

Always ask:

1. One-line project description — "What does this project do in one sentence?"
2. Core principles — "What are 3-5 rules that should always guide development in this project?" (Offer examples based on what you've seen in the codebase)
3. Project story — Suggest a short metaphor or narrative that connects the project name to its purpose (2-3 sentences). This goes in the README header to give the project personality. Look for a metaphor grounded in what the name evokes — a physical object, a place, an action — and connect it to what the software actually does. Propose a suggestion and let the user refine it.

Ask only if ambiguous from code: 4. Confirm detected commands if multiple options exist (e.g., npm vs bun) 5. Confirm project structure if unclear (monorepo vs single app) 6. External dependencies — "Does this project depend on external services or APIs? List them with how to verify they're working (e.g., health-check endpoints, test commands)." 7. Debugging patterns — "When something breaks, what should be checked first?" (e.g., env/config files, specific log locations, common failure modes) 8. Preferred libraries — "Are there preferred libraries or patterns for common tasks that new code should follow?"

Never ask what's discoverable from code:

• Language, framework, test runner, linter — detect these automatically
• Available scripts — read package.json/Makefile
• Directory structure — explore it

Step 4: Generate CLAUDE.md

Create CLAUDE.md following this exact structure:

# <Project Name>

<one-line description from Step 3>

## Commands

<all discovered commands in a code block — install, dev, build, check, lint, format, typecheck, test, etc.>

## Documentation

| Document | Purpose |
|----------|---------|
| [Architecture](docs/architecture.md) | System design, data flow, package responsibilities |
| [Development](docs/development.md) | Prerequisites, setup, daily workflow |
| [Coding Guidelines](docs/coding-guidelines.md) | Code style, error handling, naming conventions |
| [Testing](docs/testing.md) | Test commands, conventions, patterns |
| [PR Workflow](docs/pr-workflow.md) | Commits, PRs, branch naming, review process |
<additional project-specific docs rows if applicable>

## Core Principles

<3-5 principles from Step 3, as a numbered list>

## Commits

Format: `<type>(<scope>): <description>`

Types: feat, fix, docs, refactor, test, chore, perf

<2-3 example commit messages using actual project scopes>

## External Dependencies

<services, APIs, and tools the project depends on — with verification commands>

## Debugging

<what to check first when things break — project-specific troubleshooting patterns>

## Conventions

<naming patterns, preferred libraries, and project-specific rules beyond commit format>

Optional sections: Include ## External Dependencies, ## Debugging, and ## Conventions only when the user provides relevant information in Step 3. Do not generate empty sections or invent content.

Critical rules:

• Commands block must contain ONLY commands that actually exist in the project
• Every command must be verified against package.json scripts, Makefile targets, or equivalent
• Use <!-- TODO: verify this command --> if uncertain about a command
• Core principles must come from user input, not be invented

Step 5: Create AGENTS.md, .claude/settings.local.json, and .gitignore

# Create AGENTS.md as a symlink to CLAUDE.md
ln -sf CLAUDE.md AGENTS.md

# Create .claude directory
mkdir -p .claude

If .claude/settings.local.json already exists, merge the attribution keys into it. If it doesn't exist, create it:

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

The empty attribution fields suppress Claude Code's default Co-Authored-By lines. This file is user-local and not committed — the "no attribution" rule is also documented in CLAUDE.md for enforcement.

Create .gitignore if it doesn't exist. If it already exists, ensure .claude/ is listed.

The .claude/ directory contains only user-specific settings (settings.local.json with tool permissions and attribution) and should not be committed.

# Check if .gitignore exists
if [ ! -f .gitignore ]; then
  # Create with .claude/ entry
  echo ".claude/" > .gitignore
else
  # Add .claude/ if not already present
  grep -qxF '.claude/' .gitignore || echo '.claude/' >> .gitignore
fi

Add other standard entries based on the detected tech stack:

• Node/Bun: node_modules/, dist/, .env, .env.local
• Go: binary name, vendor/ (if not committed)
• Python: __pycache__/, .venv/, *.pyc
• Rust: target/
• General: .DS_Store, *.log, coverage/

IMPORTANT: If .gitignore already exists, do NOT overwrite it. Only append missing entries.

Step 6: Generate /docs

Create the docs/ directory and generate five core documentation files plus any project-specific extras.

mkdir -p docs

Five core docs (always created):

docs/architecture.md

# Architecture

<system design overview — what the project is, how it's structured>

## Project Structure

<directory tree with annotations for key directories>

## Data Flow

<how data moves through the system — request lifecycle, processing pipeline, etc.>

## Package/Module Responsibilities

<table or list of key packages/modules and what they do>

<!-- TODO: Add diagrams if helpful -->

docs/development.md

# Development

## Prerequisites

<runtime, language version, tools needed — detected from project>

## Setup

<step-by-step from clone to running — based on actual project setup>

## Daily Workflow

<common development loop — start dev server, run tests, etc.>

## Available Commands

<full list of all scripts/make targets with descriptions>

docs/coding-guidelines.md

# Coding Guidelines

## Code Style

<detected style rules — formatter, linter config, import ordering, etc.>

## Error Handling

<project's error handling patterns — detected from code or marked TODO>

## Naming Conventions

<file naming, function naming, variable naming patterns detected>

## Documentation

<when to add comments, docstring conventions, etc.>

<!-- TODO: Add examples from the codebase -->

docs/testing.md

# Testing

## Running Tests

<exact test commands from project>

## Test Conventions

<test file location, naming, framework-specific patterns>

## Writing Tests

<patterns detected in existing tests — describe what you see>

## Coverage

<coverage commands if available, coverage expectations>

docs/pr-workflow.md

# PR Workflow

## Commit Conventions

Format: `<type>(<scope>): <description>`

Types: feat, fix, docs, refactor, test, chore, perf

### Examples

<2-3 examples using actual project scopes>

## Branch Naming

Format: `<type>/<issue-number>-<short-kebab-description>`

### Examples

<2-3 examples relevant to the project>

## PR Checklist

- [ ] Code follows project guidelines (see [Coding Guidelines](coding-guidelines.md))
- [ ] Tests added/updated (see [Testing](testing.md))
- [ ] Documentation updated (if applicable)
- [ ] CHANGELOG.md updated for user-facing changes
- [ ] Lint/format checks pass
- [ ] All tests pass

## Review Process

<project-specific review norms, or standard forge workflow>

Additional project-specific docs — offer based on detection:

Use AskUserQuestion to offer detected extras:

Based on what I found in the codebase, I'd also suggest creating:
- docs/api-reference.md (detected REST routes in src/routes/)
- docs/deployment.md (detected Dockerfile and docker-compose.yml)

Which of these would you like me to create?

Content rules for all docs:

• Every sentence must be specific to THIS project — no generic filler
• Use <!-- TODO: ... --> for anything that can't be determined from code
• Reference actual file paths, actual commands, actual patterns found in the codebase
• Keep each doc focused — if it's getting long, you're adding too much

Step 7: Generate README.md

If no README.md exists, create one following this structure:

<p align="center">
  <strong><one-line project description></strong><br>
  <short tagline — a punchy subtitle that complements the description>
</p>

<p align="center">
  <a href="docs/architecture.md">Architecture</a> &middot;
  <a href="docs/development.md">Development</a> &middot;
  <a href="docs/coding-guidelines.md">Guidelines</a> &middot;
  <a href="docs/testing.md">Testing</a> &middot;
  <a href="docs/pr-workflow.md">PR Workflow</a>
</p>

---

<project story from Step 3 — the metaphor connecting the name to the purpose>

---

## Quick Start

<minimal steps to get running — clone, install, start>

## Features

<bullet list of key features — derived from codebase exploration>

## Development

<essential dev commands — install, dev, test, lint>

See [Development Guide](docs/development.md) for full setup instructions.

## Documentation

| Document | Purpose |
|----------|---------|
| [Architecture](docs/architecture.md) | System design and data flow |
| [Development](docs/development.md) | Setup and daily workflow |
| [Coding Guidelines](docs/coding-guidelines.md) | Code style and conventions |
| [Testing](docs/testing.md) | Test commands and patterns |
| [PR Workflow](docs/pr-workflow.md) | Commits, PRs, and review process |

## Contributing

1. Create an issue: `/forge-create-issue`
2. Implement: `/forge-implement-issue <number>`
3. Self-review: `/forge-reflect-pr`
4. Address feedback: `/forge-address-pr-feedback`
5. Update changelog: `/forge-update-changelog`

Header rules:

• If the project has a logo (assets/logo.svg or similar), add a centered <img> above the tagline
• The story paragraph goes between two --- dividers, right after the nav links
• Keep the story to 2-3 sentences — evocative, not verbose

If README.md already exists, use AskUserQuestion:

A README.md already exists. How would you like to proceed?
1. Replace it entirely with the new structure
2. Merge — keep existing content and add missing sections
3. Keep the existing README.md unchanged

Step 8: Generate CHANGELOG.md

If no CHANGELOG.md exists, create one with header only:

# Changelog

All notable user-facing changes to this project will be documented in this file.

Changes are grouped by release date and category. Only user-facing changes are included — internal refactors, test updates, and CI changes are omitted.

If the project has existing git history, use AskUserQuestion:

This project has existing git history. Would you like me to backfill the changelog from recent commits?
1. Yes — scan recent commits and create initial entries
2. No — start fresh from this point forward

If backfilling, follow the forge-update-changelog conventions (user-facing, plain language, no jargon).

Step 9: Commit

Stage all new and modified meta files and commit:

# Stage only the meta files we created/modified
git add CLAUDE.md AGENTS.md .gitignore docs/ README.md CHANGELOG.md

# Commit with conventional format
git commit -m "docs: add agentic engineering meta-structure"

Do NOT commit if:

• The user asked for a dry run
• There are unrelated staged changes (unstage them first)
• Any generated file has unresolved questions (ask user first)

Step 10: Summary

Present a summary of everything that was created:

## Setup Complete

### Files Created
- CLAUDE.md — Project guide with commands, docs table, principles, commit conventions
- AGENTS.md — Symlink → CLAUDE.md
- .claude/settings.local.json — Attribution settings (user-local, not committed)
- .gitignore — Git ignore rules (includes .claude/)
- docs/architecture.md — System design and structure
- docs/development.md — Prerequisites, setup, workflow
- docs/coding-guidelines.md — Code style and conventions
- docs/testing.md — Test commands and patterns
- docs/pr-workflow.md — Commit, PR, and review conventions
<any additional docs created>
- README.md — Project overview and quick start
- CHANGELOG.md — Ready for entries

### Next Steps
1. Review each generated file and fill in any <!-- TODO --> markers
2. Use /forge-create-issue to plan your first piece of work
3. Use /forge-implement-issue to start implementing

Important Guidelines

Content Quality

• No generic boilerplate: Every sentence must be specific to the project. "This project uses React" is specific. "Follow best practices" is not.
• Placeholders over fiction: If you can't determine something from the code, use <!-- TODO: describe X --> rather than making something up.
• Derived from exploration: Commands, structure, patterns — all must come from actual codebase analysis, not assumptions.

What NOT to Do

• Don't generate docs for a tech stack you didn't detect
• Don't invent project principles — ask the user
• Don't include attribution lines (Co-Authored-By, etc.) in any commits
• Don't include time estimates anywhere
• Don't add commands to CLAUDE.md that don't exist in the project
• Don't create AGENTS.md as a regular file — it must be a symlink
• Don't generate content that contradicts existing project configuration

Handling Edge Cases

• Monorepo: Create root-level meta files that reference sub-packages. Suggest per-package CLAUDE.md files as a follow-up.
• No tests yet: Create docs/testing.md with <!-- TODO --> markers and recommend setting up a test framework.
• No CI yet: Skip docs/ci.md but mention it as a follow-up in the summary.
• Multiple languages: Document all detected languages in CLAUDE.md commands section, grouped by language.

Related Skills

Next step: Use forge-create-issue to plan your first piece of work. Full workflow: forge-setup-project → forge-create-issue → forge-implement-issue → forge-reflect-pr → forge-address-pr-feedback → forge-update-changelog

Example Usage

/forge-setup-project
/forge-setup-project /path/to/project