Project-Local Bundles — 5-Minute Quickstart

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

First time using AIWG? Begin with Install, Connect, and Verify. This guide assumes AIWG is already installed, `all` is deployed for your provider, and the agent-owned context regeneration procedure has connected the agent to this project.

Author your first project-local AIWG bundle without forking anything.

What you'll build

A project-local extension that adds a custom rule to your project — only your project, not anyone else's — and deploys it alongside the upstream SDLC framework.

Prerequisites

• AIWG installed: the agent-owned version operation returns ≥ `2026.5.0`
• A project with `.aiwg/aiwg.config` (run the agent-owned init operation if not)

Steps

1. Scaffold

Use AIWG to complete this documented outcome: 1. Scaffold
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Output:

✓ Scaffolded project-local extension 'my-team-rules' at /…/my-project/.aiwg/extensions/my-team-rules
  Files created:
    + manifest.json
    + README.md
    + rules/my-team-rules.md

Next steps:
  1. Edit manifest.json (description, version, keywords)
  2. Customize the starter artifact under .aiwg/extensions/my-team-rules/
  3. Deploy:  the agent-owned use operation my-team-rules
  4. Inspect: the agent-owned doctor operation the project-local option

2. Customize the rule

Edit `.aiwg/extensions/my-team-rules/rules/my-team-rules.md`:

---
id: no-vendored-edits
---

# no-vendored-edits

Never modify files under `vendor/` or `node_modules/`.

## Why
Vendored code is replaced wholesale on dependency updates, so any local
edit silently disappears the next time someone runs `npm install`.

## How to apply
If a fix needs to land in vendored code, file an upstream PR or vendor a
fork. Don't edit in place.

3. Deploy

Use AIWG to complete this documented outcome: 3. Deploy
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The deploy pipeline picks up the bundle, validates it, runs shadow resolution against the upstream registry, and writes `.claude/rules/no-vendored-edits.md` (and the same for any other configured providers).

4. Verify

Use AIWG to complete this documented outcome: 4. Verify
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

You should see your bundle listed under "Project-local artifacts" with zero validation errors and zero drift.

cat .aiwg/activity.log | tail -5

You'll see a `deploy` entry confirming the artifact landed.

5. Iterate

Edit the rule, re-run the agent-owned use operation, and the deployed file gets refreshed. The `installed` registry entry's `artifactHashes` is updated so a future the agent-owned remove operation can detect operator mutations.

6. Tidy up

Use AIWG to complete this documented outcome: 6. Tidy up
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Reverts the deployed file. The bundle source under `.aiwg/extensions/` is never deleted by `remove` — only `rm -rf` does that, and only when you ask for it explicitly.

What just happened

You ran	What happened
the agent-owned new-bundle operation	Created `.aiwg/extensions/my-team-rules/` with valid manifest + starter; if your `.gitignore` blanket-ignored `.aiwg/`, AIWG appended a managed un-ignore block so the bundle source is tracked by git
the agent-owned use operation	Discovered, validated, resolved shadows, deployed to provider paths, recorded artifactHashes
the agent-owned doctor operation	Reported counts, validation, shadows, drift, and any bundles silently git-ignored — all from the registry + filesystem
the agent-owned remove operation	Hash-checked deployed file (pristine), deleted it, dropped registry entry; source preserved

A note on `.gitignore`

AIWG-managed projects historically `.gitignore` the whole `.aiwg/` tree because most of its content is generated state (working scratch, ralph state, research corpora, etc.). Project-local bundle source under `.aiwg/{addons,extensions,frameworks,plugins,providers}/`, legacy `.aiwg/quickref.json`, and managed `.aiwg/quickref.config.json` are exceptions — they are operator-authored, and they should travel with the project.

the agent-owned new-bundle operation detects this and self-heals: when it finds a blanket `.aiwg/` ignore rule and no existing source-directory negation, it appends a sentinel-marked block:

# AIWG project-local bundle source — track these (managed by AIWG)
!.aiwg/aiwg.config
!.aiwg/quickref.json
!.aiwg/quickref.config.json
!.aiwg/addons/
!.aiwg/extensions/
!.aiwg/frameworks/
!.aiwg/plugins/
!.aiwg/providers/

The block is idempotent (re-running `new-bundle` doesn't duplicate it) and a no-op when:

• there's no `.gitignore` (the project may not be using git)
• `.aiwg/` isn't blanket-ignored (you've configured selective ignores)
• you already have an explicit `!.aiwg/...` negation (you're managing this yourself)

If you adopted project-local bundles before this self-heal landed, run the agent-owned doctor operation — it surfaces any bundle whose `manifest.json` is currently git-ignored, with the exact lines to add to `.gitignore`.

Next steps

• Add more artifacts (`skills/`, `agents/`, `commands/`) — see `project-local-lifecycle.md`
• Pick the right type for your next bundle — see `extensions-vs-addons-vs-frameworks-vs-plugins.md`
• Graduate to upstream — see "Graduation" in the lifecycle doc

Script-backed skills

For a per-repo skill that runs a script, put both the `SKILL.md` and its script inside the project-local bundle:

.aiwg/extensions/my-team-tools/
├── manifest.json
└── skills/
    └── my-check/
        ├── SKILL.md
        └── scripts/
            └── my_check.py

Declare the script in `SKILL.md` frontmatter:

---
name: my-check
description: Run the project-specific check.
script:
  entrypoint: scripts/my_check.py
  runtime: python3
  cwd: project-root
---

# my-check

Run the project-specific check and report failures.

Deploy the bundle, then run the skill:

Use AIWG to complete this documented outcome: Deploy the bundle, then run the skill
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

By default, skill scripts run from the calling project root, not the skill directory. Relative paths such as `.aiwg/`, `src/`, and `package.json` therefore resolve against your repository.