Skip to content
fx-blog
AI Agents: SDLC & STLCagentic-fx: Install · Part 1 of 1

Install Claude Code Bundles Without Breaking Your Own Files

Copying Claude Code bundles by hand misplaces files and hides stale versions. npx agentic-fx@latest install records every file it writes in .claude/.agentic-fx.json, and update and uninstall touch only files on that list.

Harry4 min readBeginner
  • Verification
  • Value
MarkdownSave

Key takeaways

  • Copying Claude Code bundles by hand puts files in the wrong place, can leave a second bundle without its hooks, and gives no sign that a copy is stale.
  • npx agentic-fx@latest install copies a bundle's agents, commands and skills into .claude/, its workspace into .sdlc/, .stlc/ or .evals/, and merges its settings.json rules and hooks.
  • Every file the installer owns is recorded in .claude/.agentic-fx.json, and update and uninstall act only on files on that list.
  • Your profile and your own settings.json rules survive an update; a file a new version no longer ships is deleted only after you confirm.
  • doctor reports a missing .claude folder, and outdated shows installed against published versions for each bundle.
Contents

TL;DR Install Claude Code bundles by hand and files land in the wrong place, old versions go unnoticed, or an update overwrites your work. npx agentic-fx@latest install records every file it writes in .claude/.agentic-fx.json; update and uninstall touch only files on that list.

Do this: in a project you can throw away, run npx agentic-fx@latest install, then open .claude/.agentic-fx.json to see what it owns.

You copy a bundle's agents, commands and skills into .claude/ on Monday. The bundles here are dev (software delivery), qa (testing) and eval (LLM evaluation).

A month later a fix ships. You copy again, over the file you tweaked. Or you don't. Nothing tells you which.

What goes wrong when you copy by hand

None of it throws an error. A file in the wrong folder just sits there. Two bundles each ship a settings.json; copy the second over the first and one bundle runs without its hooks. And a copied folder has no version, so you can't tell it is stale.

Five questions to ask of any installer

Question agentic-fx
Can I see what it wrote? One list: .claude/.agentic-fx.json
What about a file I edited? Your profile is kept; bundle files are replaced
And my settings? Rules and hooks are added, none removed
Will I hear about new versions? The board and Claude Code read a notice file
Can I remove it? uninstall deletes listed files only

How the installer works, step by step

The installer in five steps: --bundle dev,qa in, dev 1.10.0 copied into .claude/, settings.json merged, owned files recorded, workspaces and profiles out

  1. Input. A project and --bundle dev,qa,eval or all; with no flag it asks. It checks Node 20+, Claude Code, Git Bash on Windows and Python for eval, and blocks on none.
  2. Copy. Agents, commands and skills go to .claude/, the workspace to .sdlc/, .stlc/ or .evals/. A profile is copied only if you have none.
  3. Merge. New rules and hooks are appended to settings.json.
  4. Record. Every owned file goes into the manifest.
  5. Output. A profile per bundle to fill, and the VS Code board unless you pass --no-addons.

Step 3 is where this differs from the installer I use in-house. That one leaves a second settings file for you to merge by hand. Fine for me. Someone installing two bundles from npm would run the second with its hooks silently off, so this one merges, and only ever adds.

One real run: a deleted folder and an old version

An empty git repo called my-project, then npx agentic-fx@latest install --bundle dev,qa --no-addons --yes:

The install in my-project: machine checks pass, dev 1.10.0 and qa 2.5.0 installed into .sdlc/ and .stlc/

ls -AF -C -T 0 -w 76 .claude .sdlc .stlc shows where it went. The manifest lists 507 files.

.claude/ after install, with the manifest .agentic-fx.json, both profiles and the agents, commands, hooks and skills folders, beside .sdlc/ and .stlc/

Then I broke it. A line in DEV-PROFILE.md, a permission rule of my own in settings.json, rm -rf .claude/skills, and npx agentic-fx@latest doctor:

doctor after the delete: dev 1.10.0 and qa 2.5.0 both marked missing .claude/skills, run update

npx agentic-fx@latest update --no-addons put the skills back. tail -n 1 .claude/DEV-PROFILE.md still printed my line, my rule was still there, and doctor went green.

update restores both bundles, tail shows the profile line still in place, doctor marks dev and qa green

Last, I set dev to 1.8.0 in the manifest, standing in for an older install, and ran npx agentic-fx@latest outdated:

outdated: dev 1.8.0 to 1.10.0, minor; qa 2.5.0 up to date

npx agentic-fx@latest update --bundle dev --no-addons moved it to 1.10.0. A MAJOR release would ask first.

Get it

Try it
cd your-project
npx agentic-fx@latest install
claude

Fill the profile, then run /sdlc-intake <slug>, /qa-analyze <slug> <docs…> or /eval-scope. You need Node 20+ and Claude Code.

What does a gate in dev actually check? Read Your AI Coding Agent Grades Its Own Homework. Add Gates. Testing starts with A QA Pipeline Your AI Agent Can't Fake.

Read this with your AI

textPaste into your AI
Read the post "Install Claude Code bundles without breaking your own files".
1. Summarise it in 5 bullets for a tech lead.
2. Ask me 3 questions to check I understood; wait, then correct me.
3. Give me one 10-minute exercise for my own project.

FAQ

Which bundles does npx agentic-fx@latest install?

It installs dev (software delivery), qa (testing) and eval (LLM and agent evaluation) with `--bundle dev,qa,eval` or `--bundle all`. With no flag it asks, and with `--yes` and no flag it installs all three.

Does an update overwrite my profile or settings?

No. The profile (`DEV-PROFILE.md`, `PROJECT-PROFILE.md` or `EVAL-PROFILE.md`) is kept, and settings.json only gains rules and hooks it lacks. Files the bundle owns are replaced, so edit the profile, not the bundle files.

How do I skip the VS Code board?

Pass `--no-addons`. Without it, the board is installed into VS Code, Cursor or Windsurf, whichever command is found on the machine.

Sources

  1. agentic-fx on npm
  2. agentic-fx-npm on GitLab
agentic-fx

Was this useful?

Only you and the owner see your answer and rating. Send private feedback

Enjoyed it? Support fx-blog with a coffee.

Related posts

AI Agents: SDLC & STLC

The QA Board and the Release Gate

"May it ship?" should not be answered in a chat. The stlc board on orders checkout, and a QA release gate: a report verdict derived from its gate rows, rejected by lint if it disagrees, which the dev deploy step reads before checkout ships.

4 min readAdvanced
stlc

Comments

Oldest first

No comments yet. Start the conversation.

You sign in first; what you typed stays here. · 0 / 2,000