Project-Local Lifecycle

Bundle lifecycle and graduation

Project-Local Artifact Lifecycle

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.

Reference for managing project-local bundles across all five bundle types over their full lifetime: discovery → deploy or provider selection → conflict resolution → inspection → graduation → removal.

Layout

.aiwg/
├── extensions/<id>/    # Single-capability bundles
├── addons/<id>/        # Focused feature packs
├── frameworks/<id>/    # Complete workflow domains
├── plugins/<id>/       # Marketplace-packaged bundles
├── providers/<id>/     # Custom provider definitions
├── quickref.config.json # Optional managed quickref overrides
└── quickref.json        # Legacy complete v1 quickref definition (optional)

The logical `.aiwg/` root is resolved through the same project artifact configuration as the rest of AIWG. If the project has `.aiwg-location` or `AIWG_ARTIFACTS_PATH`, discovery, scaffolding, quickref generation, registry bindings, and reindexing follow that configured directory instead of assuming `<project>/.aiwg`.

Operators can add extra bundle roots for team/private extensions without moving the main project corpus:

{
  "version": "1",
  "providers": ["claude"],
  "installed": {},
  "scripts": {},
  "projectLocal": {
    "searchPaths": ["../team-aiwg-bundles", "~/aiwg-private-bundles"]
  }
}

Each additional search root uses the same child layout (`addons/`, `extensions/`, `frameworks/`, `plugins/`, `providers/`). For one-off operator sessions, set `AIWG_PROJECT_LOCAL_PATHS` to a platform-delimited list of roots.

Each `<id>/` contains a `manifest.json`. Artifact-bearing bundles also contain artifacts (skills/, rules/, agents/, commands/). Provider bundles are metadata-only in phase 0: `providerConfig.extends` selects an existing writer adapter while preserving a custom provider id at the CLI boundary. Provider bundles may also declare `providerConfig.capabilities` as data-only overrides consumed by the agent-owned steward operation. The directory is byte-identical in shape to its upstream counterpart at `agentic/code/{addons,frameworks,providers}/` so the agent-owned promote operation is a copy, not a migration.

Lifecycle commands

Command	Action
the agent-owned new-bundle operation	Scaffold a new bundle with manifest + starter + README
the agent-owned new-provider operation	Scaffold a custom provider bundle under `.aiwg/providers/`
the agent-owned use operation	Deploy a single project-local bundle to configured providers
the agent-owned use operation	Select a project-local provider bundle
the agent-owned use operation	Deploys upstream + auto-deploys all project-local bundles
the agent-owned list operation	List discovered bundles + validation status
the agent-owned doctor operation	Health check: counts, validation, shadows, drift, matrix
the agent-owned remove operation	Revert deployed files; preserves source under `.aiwg/`
the agent-owned promote operation	Graduate a bundle to upstream or a corpus path
the agent-owned activity-log operation	Audit the lifecycle event log
the agent-owned quickref operation	Render the deterministic project quickref skill
the agent-owned quickref operation	Deploy the quickref to configured provider kernel surfaces

Discovery

the agent-owned use operation, the agent-owned doctor operation, and the agent-owned list operation all run the same discovery scanner. It walks the configured artifact root plus any `projectLocal.searchPaths` / `AIWG_PROJECT_LOCAL_PATHS` roots for `{extensions,addons,frameworks,plugins,providers}/<id>/manifest.json`. It validates each `manifest.json` against the canonical Zod schema and returns structured results.

What discovery enforces:

Manifest matches the JSON Schema (kebab-case ids, ≤ 64 KB, ≤ 200

bundles per project)

Bundle type matches its parent directory (`type: extension` lives

under `extensions/`)

No symlinked bundle directories (refused per threat model #1042)
No case-collision ids within the same type
Path-traversal attempts in entry paths are refused

Validation errors are surfaced — they never crash the operation.

Deploy

the agent-owned use operation deploys a specific artifact-bearing project-local bundle. the agent-owned use operation (e.g., `sdlc`) deploys the upstream framework and all project-local bundles in the same pass.

Provider bundles are selected, not deployed as artifact bundles:

Use AIWG to complete this documented outcome: Provider bundles are selected, not deployed as artifact bundles
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The generated manifest contains `providerConfig.extends` (default: `claude`). In phase 0, this delegates output writing to the existing provider adapter. It does not define new writer behavior or new filesystem targets by itself.

To customize steward guidance, add optional capability overrides:

{
  "providerConfig": {
    "extends": "codex",
    "displayName": "my-codex",
    "capabilities": {
      "nativeFeatures": { "cron": true },
      "emulation": { "mission_control": "aiwg-mc" }
    }
  }
}

Supported feature keys are `cron`, `agent_teams`, `tasks`, `mcp`, `behaviors`, `mission_control`, and `daemon`. Invalid feature keys fail manifest validation.

Per-bundle deploy: 1. Resolve shadows against the upstream registry 2. Refuse to deploy bundles with safety-critical shadows that lack explicit `overrides:` declarations (or with phantom overrides, or with cross-bundle artifact-id collisions) 3. Run `tools/agents/deploy-agents.mjs` with the source option pointing at the bundle directory 4. Compute SHA-256 of every artifact and persist as `artifactHashes` in the registry — used later by the agent-owned remove operation and the agent-owned doctor operation for drift detection 5. Emit `deploy` (or `deploy-failed`) to the activity log

the dry-run option and the no-project-local option are supported.

Each project-local deploy resolves a managed quickref from discovered bundles (or a legacy `.aiwg/quickref.json`) and refreshes that provider's project quickref. The generated skill stays short: it states local precedence and points to indexed assets rather than embedding their full bodies. See Project Quickrefs.

Conflict resolution (shadow policy)

When a project-local artifact has the same id as an upstream artifact, the resolver chooses one of seven verdicts (ADR #1041):

#	Case	Default	the force option?
1	No collision	deploy	n/a
2	Non-safety-critical shadow	deploy + warn	n/a
3	Safety-critical shadow + explicit `overrides:`	deploy with prominent warning	n/a
4	Safety-critical shadow without `overrides:`	refuse	refuse (force does NOT bypass)
5	Phantom override (`overrides: ["nonexistent"]`)	refuse	refuse
6	Two project-local bundles export same artifact	refuse both	refuse both
7	Git-installed (cache) shadow	same as cases 2/3/4 against the cache	n/a

To shadow a safety-critical upstream artifact intentionally, declare it:

{
  "type": "extension",
  "id": "my-overrides",
  "overrides": ["human-authorization"],
  ...
}

The override is logged as `shadow-acknowledged` in the activity log and prominently warned in deploy output and the agent-owned doctor operation.

Inspection: the agent-owned doctor operation

Use AIWG to complete this documented outcome: Inspection: the agent-owned doctor operation
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The project-local section reports:

Per-type counts with bundle id listing
Validation errors (top 10 inline, "+N more" if longer)
Active shadows (informational ⚠ for non-safety, !! for acknowledged)
Denylist violations (✗)
Drift — deployed file hash differs from registered `artifactHashes`
Provider deployment matrix

Doctor exits 0 when there are no validation errors, no denylist violations, and no drift. Shadows alone do not fail doctor (they're informational).

Removal: the agent-owned remove operation

Use AIWG to complete this documented outcome: Removal: the agent-owned remove operation
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Source under `.aiwg/<type>/<name>/` is never deleted by the agent-owned remove operation. the force option skips the case-2 prompt only — it does not authorize destroying another bundle's deploy (case 4) and does not bypass OS permission errors (case 5).

For the full per-case revert behavior, see `design-aiwg-remove-revert.md`.

Graduation: the agent-owned promote operation

When a bundle proves out and you want to move it from project-local to upstream (or to a private corpus path):

Use AIWG to complete this documented outcome: When a bundle proves out and you want to move it from project-local to upstream (or to a private corpus path)
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

What promote does: 1. Discovers the bundle 2. Refuses if the destination already exists (must the agent-owned remove operation from upstream first) 3. Refuses if the bundle contains `@.aiwg/` references (they'd dangle after the move) — the force option overrides 4. SHA-256 snapshots every source file 5. Recursive copy to the destination (`agentic/code/addons/<name>/` for extension/addon/plugin, `agentic/code/frameworks/<name>/` for framework, `agentic/code/providers/<name>/` for provider) 6. Re-hashes every destination file; rolls back (deletes the dest directory) on any mismatch 7. Updates the registry: `source: 'project-local'` → `'bundled'` (or `'corpus'`) 8. Optionally removes the `.aiwg/<type>/<name>/` source (the cleanup option) 9. Emits `promote` (or `promote-failed`) to the activity log

The hash-verify step makes the identical-form invariant a runtime guarantee, not a convention.

Activity log

Every project-local lifecycle event writes a single line to `.aiwg/activity.log` in the canonical format:

## [YYYY-MM-DD HH:MM] <op> | <event>: <name>:<type> | <summary>

The 12 events:

`discover` — new manifest detected (deduped)
`deploy`, `deploy-failed`
`conflict`, `shadow-acknowledged`, `shadow-refused`
`remove`, `remove-mutated`, `remove-conflict`, `remove-force`
`promote`, `promote-failed`

Query:

Use AIWG to complete this documented outcome: The 12 events: - discover — new manifest detected (deduped) - deploy, deploy-failed - conflict, shadow-acknowledged, shadow-refused - remove, remove-mutated, remove-conflict, remove-force - promote, promote-failed
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Writes are non-blocking: if the log can't be written, the underlying operation still succeeds.

When project-local is the wrong answer

Project-local is the right answer for personal or single-team customization that you want to graduate later or never share. It is the wrong answer for:

Customizations destined for the public AIWG marketplace — author

upstream and use a plugin

Cross-project customizations shared across many of your repositories —

use a corpus path with the agent-owned promote operation and reference via the agent-owned config operation

Forking AIWG itself — only when you need to change AIWG core, not when

you're adding addons/extensions

For the migration story, see the forking guide.