[zwanski-start]

Closes #87

What changed

Docs-only change to README.md:

• New "Claude Code Skills, Commands & Agents" section with a table explaining each item in .claude/, who uses it, and whether it needs installing. In short: nothing needs to go into ~/.claude to use AutoForge itself:
  • create-spec / expand-project commands are read straight from AutoForge's install dir (server/services/spec_chat_session.py, expand_chat_session.py)
  • templates/ are copied into each project's .autoforge/prompts/ (prompts.py)
  • skills/playwright-cli is copied into each project's .claude/skills/ (prompts.py)
  • dev-only agents, commands and skills are picked up automatically when running claude inside the AutoForge repo
• Step-by-step instructions for the one case that does need manual setup: using gsd-to-autoforge-spec on an existing project. It covers symlinking or copying the skill into ~/.claude/skills/ or <project>/.claude/skills/ (npm and source installs, plus a Windows note), then /gsd:map-codebase, then "convert to autoforge".
• Updated the Project Structure tree so .claude/ lists agents/ and points to the new section.

Verification

• Checked each claim against the code paths above, and against package.json files (.claude/commands, skills, templates ship with npm) and .npmignore (.claude/agents/ does not).
• No code changes, so no tests are affected.

Assumptions

• I recommend installing the skill rather than the /gsd-to-autoforge-spec command, because the command file includes the skill through a project-relative path (@.claude/skills/...) and breaks if it's copied alone. The README notes this.
• I left out a link to the GSD project, because the repo doesn't reference a canonical URL for it.

🤖 Generated with Claude Code

[zwanski-start]

🔍 QA report: ✅ Passed

Tester: Ken (cubefarm agent, in a fresh session) · Round: 1 · Author: Guido

Docs-only PR that answers issue #87: nothing in .claude/ needs to go into ~/.claude to use AutoForge, except gsd-to-autoforge-spec when used on an existing project, and the README gives working steps for that. Every claim in the new section matches the code (spec_chat_session.py, expand_chat_session.py, prompts.py, package.json files, .npmignore), and the shell commands work as written. Lint and build checks are green.

	Check	Details
✅	Issue #87 question answered (do .claude items need installing into ~/.claude?)	The new README section has a table that says, for each item, who uses it and whether it needs installing. Only gsd-to-autoforge-spec does, and the section gives step-by-step instructions for it (copy or symlink, /gsd:map-codebase, 'convert to autoforge', register and run).
✅	create-spec / expand-project read from AutoForge install dir	spec_chat_session.py:86 and expand_chat_session.py:104 read ROOT_DIR/.claude/commands/*.md.
✅	templates and playwright-cli copied into each project	In prompts.py, scaffold_project_prompts copies the templates into .autoforge/prompts/ and copies .claude/skills/playwright-cli into the project's .claude/skills/.
✅	npm packaging claims	package.json 'files' includes .claude/commands/, skills/ and templates/. .npmignore excludes .claude/agents/. The package name autoforge-ai matches the $(npm root -g)/autoforge-ai path in the README.
✅	Command file depends on the skill through a project-relative path	.claude/commands/gsd-to-autoforge-spec.md contains '@.claude/skills/gsd-to-autoforge-spec/SKILL.md', so the README's advice to install the skill is correct.
✅	Step 4: registering an existing folder keeps the generated app_spec.txt	POST /api/projects accepts an existing directory. scaffold_project_prompts only copies a template when the destination file does not exist, so a converter-generated app_spec.txt is kept.
✅	README shell commands work	Ran the ln -s and cp -r commands with a temporary HOME. Both worked, and the copy kept the references/ subfolder.
✅	No code changes or regressions	git diff --name-only shows only README.md. The worktree was left clean.
⏭️	Browser/UI check	Docs-only change. Nothing in the UI or served app changed.

🧪 Commands run

Command	Result
git diff origin/master...HEAD	Only README.md changed (+47/-4)
venv/bin/ruff check .	All checks passed
venv/bin/python test_security.py	ALL TESTS PASSED
npm --prefix ui run lint	0 errors, 6 warnings (the PR doesn't touch the UI)
npm --prefix ui run build	tsc + vite build succeeded
README ln -s / cp -r commands run with a temporary HOME	Symlink and copy created as documented

No browser screenshots were taken in this round.

_{Posted by cubefarm · merges automatically once GitHub's checks pass}