Set up a project's meta-structure for agentic engineering — CLAUDE.md, AGENTS.md, docs/, README, and CHANGELOG. Use when starting a new project or retrofitting an existing codebase for the forge workflow.
Instrucciones de origen · Vista previa de solo lectura
name
forge-setup-project
description
Set up a project's meta-structure for agentic engineering — CLAUDE.md, AGENTS.md, docs/, README, and CHANGELOG. Use when starting a new project or retrofitting an existing codebase for the forge workflow.
disable-model-invocation
true
allowed-tools
Read, Write, Bash, Grep, Glob
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 filesls -la CLAUDE.md AGENTS.md README.md CHANGELOG.md .claude/settings.local.json 2>/dev/null
# Check for docs directoryls docs/ 2>/dev/null
# Check for any code at allls -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:
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 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:
# <ProjectName><one-linedescriptionfromStep3>## Commands<alldiscoveredcommandsinacodeblock — 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 |
<additionalproject-specificdocsrowsifapplicable>## 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<whattocheckfirstwhenthingsbreak — project-specifictroubleshootingpatterns>## Conventions<namingpatterns, preferredlibraries, andproject-specificrulesbeyondcommitformat>
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.mdln -sf CLAUDE.md AGENTS.md
# Create .claude directorymkdir -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 existsif [ ! -f .gitignore ]; then# Create with .claude/ entryecho".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.
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 <!-- 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:
<palign="center"><strong><one-lineprojectdescription></strong><br><shorttagline — apunchysubtitlethatcomplementsthedescription></p><palign="center"><ahref="docs/architecture.md">Architecture</a>·<ahref="docs/development.md">Development</a>·<ahref="docs/coding-guidelines.md">Guidelines</a>·<ahref="docs/testing.md">Testing</a>·<ahref="docs/pr-workflow.md">PR Workflow</a></p>
---
<projectstoryfromStep3 — themetaphorconnectingthenametothepurpose>
---
## Quick Start<minimalstepstogetrunning — clone, install, start>## Features<bulletlistofkeyfeatures — derivedfromcodebaseexploration>## Development<essentialdevcommands — 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 |
## Contributing1. 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
