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:

bash

# 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:

State	Description	Behavior
Greenfield	No code, no meta files	Generate everything from user input
Existing, no meta	Has code but no CLAUDE.md/docs/	Explore codebase first, then generate
Partial meta	Has some meta files (e.g., README exists)	Ask user how to handle each existing file
Full meta	All meta files already present	Offer to audit and update

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:

bash

# 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:

One-line project description — "What does this project do in one sentence?"
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)
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

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:

markdown

# <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
```

```
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

bash

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

# Create .claude directory
mkdir -p .claude

.claude/settings.local.json

already exists, merge the attribution keys into it. If it doesn't exist, create it:

json

{
  "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.

bash

# 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.

bash

mkdir -p docs

Five core docs (always created):

docs/architecture.md

markdown

# 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

markdown

# 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

markdown

# 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

markdown

# 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

markdown

# 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:

Detected Signal	Suggested Doc
REST/GraphQL routes, OpenAPI spec	`docs/api-reference.md`
Dockerfile, docker-compose	`docs/deployment.md`
CI workflow files	`docs/ci.md`
Auth middleware, security headers	`docs/security.md`
React/Vue/Svelte components	`docs/frontend.md`
Database migrations, ORM config	`docs/database.md`
Multiple packages/workspaces	`docs/monorepo.md`

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
```

```
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:

markdown

<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:

markdown

# 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:

bash

# 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:

text

## 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
```

```
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
```

```
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

forge-setup-project

NPX Install

Tags

SKILL.md Content

Set Up Project Meta-Structure

Input

Process

Step 1: Determine Project State

Step 2: Explore the Codebase

Step 3: Gather Project Information

Step 4: Generate CLAUDE.md

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

Step 6: Generate /docs

docs/architecture.md

docs/development.md

docs/coding-guidelines.md

docs/testing.md

docs/pr-workflow.md

Step 7: Generate README.md

Step 8: Generate CHANGELOG.md

Step 9: Commit

Step 10: Summary

Important Guidelines

Content Quality

What NOT to Do

Handling Edge Cases

Related Skills

Example Usage