AIWG｜为多种 AI 编程工具部署可复用项目上下文与专业工作流

access：来源确认 · npm i -g aiwg

project_type：来源确认 · Reusable project context and specialist workflows for the AI tools you already use.

<div align="center">

<a href="https://aiwg.io"><img src="docs/.public/aiwg-readme-hero-v2.png" alt="AIWG — multi-agent AI framework, one
source of truth; network connecting AI tools" width="1000"></a>

# AIWG

**Reusable project context and specialist workflows for the AI tools you already use.**

Plan software, coordinate specialist reviews, prepare campaigns, investigate incidents, organize research, curate
media, and maintain operational knowledge. AIWG combines agents, skills, rules, templates, and workflow utilities
around these tasks, adapting them to your existing AI provider.

Project artifacts carry decisions from one session to the next. Domain frameworks supply the procedures; addons extend
them with writing profiles, task loops, memory, testing tools, decision support, and other capabilities. The sections
below show what you can do, how the pieces work together, and how to use them.

The simplest setup is to paste this into a supported AI provider:

```text
Install or repair AIWG for this project by following
https://aiwg.io/setup.aiwg.yaml
Explain the plan before changing anything, preserve my existing work, and ask
me only for choices you cannot safely determine.
```

The installer detects old, broken, duplicate, and development-mode installs,
then guides you through repair or update. Once the CLI is healthy, guided
setup records an interview plan, lets you review it, and applies the selected
frameworks and integrations through the existing deployment owners. The apply
report distinguishes core readiness from optional integration failures.

For long-running agents that need an isolated executor, optionally install AIWG Cockpit with a self-hosted Agentic
Sandbox executor you control and audit:

```text
Install or repair AIWG Cockpit and Agentic Sandbox by following
https://aiwg.io/agentic-sandbox/setup.aiwg.yaml
Install the required prerequisites, explain the plan before changing anything,
preserve my existing work, and ask me about the isolation, network, storage,
and access choices you cannot safely determine.
```

This option audits the host, installs the approved Docker or KVM/libvirt runtime
and sandbox prerequisites, connects Cockpit to the real executor, applies your
resource and access choices, and verifies the control and audit path end to end.

If you prefer to install manually:

```bash
npm i -g aiwg
cd /path/to/your/project
aiwg setup --scope project --providers <provider>
aiwg setup --review
aiwg setup --apply
```

Replace `<provider>` with your AI tool's name, such as `claude`, `codex`,
`copilot`, `cursor`, `omp`, or `pi`.

The interview saves a plan without changing provider configuration. Review is
read-only; apply asks for confirmation and reports the verified outcome. Optional
Jev decision offload and direct workers require explicit opt-in. Repeating apply
resumes unfinished actions and leaves completed actions alone. See the
[guided setup reference](docs/getting-started/guided-setup.md) for headless flags,
credential references, scope choices, and recovery. For a direct complete-system
deployment, `aiwg use all --provider <provider>` remains available.

For the complete beginner path and provider-name table, see
[Install, Connect, and Verify](docs/getting-started/install-connect-verify.md).

For a lightweight install that resolves signed, versioned resources from the release host, install the executable:

```bash
npm i -g @aiwg/cli
```

> Find the architecture-evolution workflow, read its requirements, and help me apply it to this project.

See [Web-Backed AIWG Resources](docs/install/web-backed-resources.md) for source
selection, exact-version overrides, cache verification, offline use, and the
current framework-graph constraints.

For a larger project, ask your AI assistant to establish project policy as well. The agent-led setup
conversation should establish remotes, issue storage, delivery behavior,
signing policy, and provider choices; the assistant discovers the project-setup workflow and handles its tools.

macOS users: if npm fails with `EACCES` under `/usr/local/lib/node_modules`,
use the [macOS Install Guide](docs/getting-started/macos-install.md).
Agents and stewards setting up AIWG end-to-end should use the
[Agentic Install Runbook](docs/agentic-install-runbook.md).

[![npm version](https://img.shields.io/npm/v/aiwg/latest?label=npm&color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
[![npm downloads](https://img.shields.io/npm/dm/aiwg?color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/jmagly/aiwg?style=flat-square)](https://github.com/jmagly/aiwg/stargazers)
[![Node Version](https://img.shields.io/badge/node-%E2%89%A524-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
[![18 Providers](https://img.shields.io/badge/Providers-18-purple?style=flat-square)](#platform-support)
[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/docs-aiwg-io)

[![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io/badges)

[**Get Started**](#quick-start) · [**Features**](#what-you-get) · [**Agents**](#agents) · [**Decision Support**](#decision-support--bounded-decisions-offloaded-to-jev) · [**Documentation**](#documentation) · [**Community**](#community--support) · [**Badges**](https://aiwg.io/badges)

[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/BuAusFMxdA)
[![Telegram](https://img.shields.io/badge/Telegram-Join-26A5E4?logo=telegram&logoColor=white&style=flat-square)](https://t.me/+oJg9w2lE6A5lOGFh)

</div>

---

## Installation Troubleshooting

### Optional native features

The base global install intentionally excludes native packages whose lifecycle
scripts require explicit trust. Core deployment, discovery, and provider tooling
work without them. Enable only the capability you need:

> Enable the native features needed for interactive terminals, semantic search, or graph-backed artifacts in this
> workspace. Explain which dependencies are required, install only the selected features, and verify they load.

The feature installer writes a private manifest and lockfile under the AIWG user
data directory and approves scripts only for that feature. Do not set a broad
user-level npm `allow-scripts` policy. If an older install left native package
files present but unbuilt, `aiwg doctor` reports the broken capability and the
same scoped rebuild command.

### macOS npm `EACCES`

If `npm install -g aiwg` fails with `EACCES` while writing to
`/usr/local/lib/node_modules/aiwg`, npm is using a system-owned global install
directory. The [Node.js setup guide](docs/getting-started/install-node.md) covers the supported runtime and
version-manager choices. After setting up Node, run:

```bash
npm install -g aiwg
aiwg doctor
```

If Node is already installed and you need a quick recovery, one manual alternative is a user-owned npm prefix. Choose
this only after checking your existing Node version-manager configuration:

```bash
npm config set prefix ~/.local
echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
echo 'source ~/.profile' >> ~/.zprofile
source ~/.profile
npm install -g aiwg
```

See [macOS Install Guide](docs/getting-started/macos-install.md) for the full
walkthrough. Avoid `sudo npm install -g aiwg` as the default fix; it can create
root-owned npm files that break later upgrades.

### `aiwg` command not found

If `aiwg` is not found after `npm i -g aiwg`, the npm global `bin` directory is not on your `PATH`. Confirm and fix:

> Diagnose why this shell cannot find AIWG. Check the npm installation and PATH, and apply the appropriate local fix.

You can also invoke AIWG without adjusting `PATH` by using `npx aiwg doctor`. For a broader health check — version,
deployed providers, missing dependencies, kernel-skill probes — run `aiwg doctor`. See the [troubleshooting
guide](docs/troubleshooting/index.md) for the full recovery paths.

---

## What AIWG Is

AIWG gives your AI assistant reusable project context and specialist workflows. Its deployment layer connects those
instructions to your provider: `aiwg use` copies markdown and YAML source files into the paths each provider reads, so
one source of truth works across 19 named provider integrations. A twentieth `generic` adapter emits portable files
for unrecognized or custom harnesses and is not counted as a named integration.

Around that core, AIWG ships agent-facing utilities for work that benefits from additional structure: persistent
artifact memory (`.aiwg/`), background orchestration, autonomous loops, artifact indexing, cost telemetry, health
diagnostics, and more. These are tools the agent calls when the task calls for them — you stay in chat. Most are
opt-in. The deployment layer works standalone as plain text files the platform reads natively.

### Project scope, user scope, and multi-project workspaces

`aiwg use` supports project deployments, additive user mirrors, and a
user-global bootstrap:

- **Project scope** — default. Run `aiwg use all --provider <provider>` from a project root and the artifacts land in
  that provider's project paths. This keeps project-specific instructions associated with the intended repository.
  Some providers also use user-level surfaces; check the reported deployment scope. **This is the simplest start
  for a single project.**
- **User scope (additive mirror)** — `aiwg use all --provider <provider> --scope user` keeps the
  project deployment and mirrors it to `~/.claude/agents/`,
  `~/.claude/skills/`, etc.
- **Global bootstrap** — `aiwg use all --provider claude --global` installs
  framework and kernel assets in native user-level paths while leaving only
  lightweight context and provider bootstrap files in the current project.
  Ask the assistant to connect additional projects without
  deploying their own skill copies.

Several repositories under one assistant or orchestrating session are supported. See
[Working Across Multiple Projects](docs/guides/multi-project-workspaces.md) for setup, access, and sharing boundaries.

Shared user-level instructions can be useful for personal conventions, while project-local instructions keep a team's
requirements and decisions with its repository. Review both scopes when a provider uses them together. The installer
and provider inventory describe where files will go, so you can distinguish instructions that follow you across
projects from instructions intended for this workspace.

See the [Agentic Install Runbook](docs/agentic-install-runbook.md) for the
zero-to-running setup path, and the [CLI reference](docs/cli/reference.md) (under `aiwg use` →
"Scope models") for the per-provider details and the global-install rough-edge
inventory.

## Simple Building Blocks

AIWG's workflow source is readable and editable. The main building blocks are:

- **Agents** — specialist role instructions, such as Security Auditor or Test Architect, with defined responsibilities
  and supported tool access.
- **Skills** — reusable procedures an agent can find from a goal and follow during a task.
- **Commands** — explicit ways to request a workflow through the provider or CLI.
- **Rules** — constraints for the assistant to follow, with tool-based checks where configured.
- **Behaviors** — lifecycle actions and hooks on providers that support them.
- **Templates** — structures for requirements, briefs, review reports, runbooks, and other outputs.

Many assets use Markdown with YAML metadata; hooks and utilities may also include executable scripts or structured
configuration. The provider determines how each asset is loaded or invoked. A role definition is not a separate model,
and a written rule is not proof that its constraint was enforced.

## Why It Compounds

The building blocks become more useful when workflows share their outputs:

- A requirements analyst records acceptance criteria that the test engineer can later use to review coverage.
- A security reviewer reads the same design decision as the implementation agent and records concerns against that decision.
- A campaign brief gives content writers a shared audience, message, and review criteria.
- A research note connects a source to the claim it supports, so a later synthesis can revisit the original evidence.
- A runbook carries verification and recovery steps from planning into an operational change.

Frameworks package these relationships: agents, skills, rules, and templates reference one another, while `.aiwg/`
holds the project-specific work they produce. A review can follow **Primary Author → Reviewers → Synthesizer →
Approval → Archive**, using parallel execution where the provider and task support it.

For example, Monday's architecture review can become Thursday's implementation checklist. The second session needs to
read the saved artifact and check that it is still applicable, but the team has a concrete record to work from rather
than reconstructing the decision from conversation fragments.

Research on structured artifacts, multi-agent review, and recovery informs this design. The [research
foundations](#research-foundations) section preserves that background separately from claims about AIWG's own
performance.

## How You Actually Use AIWG

Describe the outcome you want in your AI tool. You do not need to learn a new command language or memorize skill
names: “Help me start a project,” “Review this design for security risks,” or “Prepare a deployment plan with rollback.”

The assistant interprets your intent, searches AIWG's capability graphs, reads the matching assets, and follows their
procedures. Discovery brings together packaged AIWG capabilities and indexed project-local custom skills, agents,
rules, and workflows; user-level assets participate when project policy allows them. Your team's indexed assets can
therefore be found through the same conversation as AIWG's built-in capabilities. Newly authored assets need to be
deployed or indexed before discovery can find them.

For everyday setup and maintenance, ask:

- “Set up the SDLC framework for this project and my AI tool.”
- “Help me configure this project's tracker, delivery, signing, and provider preferences.”
- “Create a new project for this idea.”
- “Check which AIWG capabilities are active here and fix any setup problems.”
- “Update AIWG and refresh this project's deployed assets.”

The assistant handles discovery, artifact lookup, and the selected workflow's tools, then reports the result and its
verification. Matching a capability is a starting point: the assistant still checks scope, prerequisites, and project
policy before acting.

For manual setup and maintenance, the usual commands are `aiwg use`, `aiwg init`, `aiwg refresh`, and `aiwg doctor`.
The assistant handles other tooling. Advanced command syntax lives in the [CLI reference](docs/cli/reference.md).

Deployment connects the supported workflow surface. Optional servers, storage services, and automation paths have
their own prerequisites; installing assets does not mean all those services are running. You can start with one review
or document task, then enable additional utilities as the work requires.

## What AIWG Is Not

AIWG adds context, procedures, and support utilities around the AI tools you use. The deployment core writes
provider-readable assets; optional orchestration and integration components can invoke provider runtimes or other
configured services. The [architecture overview](docs/architecture-overview.md) distinguishes those components.

It does not replace your provider subscription, your application's runtime, or the review needed before using
generated work. Most workflows operate on project artifacts and source files rather than requiring your application to
import an AIWG library. Keep generated configuration and project artifacts under the same review discipline as other
repository changes.

## Who It's For

AIWG is useful to individual developers, engineering teams, technical leaders, researchers, marketers, and operators
whose work spans several tasks or sessions. It helps when you need reusable instructions, a shared record of
decisions, or reviews from more than one perspective.

You can start at several levels: a small documentation review, a focused code audit, a campaign brief, an
investigation plan, or a complete development lifecycle. The [capability guide](docs/overview/capabilities.md) offers
task-based routes, while this README keeps the broader feature and workflow detail available below.

---

## What Problems Does AIWG Solve?

AI-assisted projects often need a deliberate way to carry context forward, recover from failed attempts, and make
review criteria explicit. AIWG provides workflows and artifacts for each of those needs.

### 1. Maintaining Context Across Sessions

Useful decisions can become scattered between conversations, issues, and source files. AIWG workflows save project
outputs in `.aiwg/`, including requirements, architecture decisions, risk notes, test strategies, and campaign
material.

A later task can consult the relevant artifact and link its own work back to it. The requirements analyst writes a use
case; the test engineer reads it to identify missing coverage; the implementation review checks whether the behavior
matches the acceptance criteria. A changed decision can be recorded and propagated through those relationships.

The structure also helps an agent select context for a large project. Instead of treating every file as equally
relevant, a task can begin with a requirement, design record, or source note and follow its supporting references.
Artifact lookup and indexing utilities help locate those records as the collection grows.

The benefit depends on keeping artifacts current and actually consulting them. A saved file is a reusable source of
context, not a guarantee that every later response will use it correctly.

### 2. Recovering from Failed Attempts

A failing test or incomplete task needs a diagnosis, not just another attempt with the same assumptions. Agent loops
support an execute-and-verify cycle that records failure information, adapts the next attempt, and stops at configured
limits or escalation conditions.

Use a loop for a bounded change with an observable completion criterion: fixing a regression, bringing a module under
test, or carrying out a migration plan. External loop tooling adds process and session recovery where supported. Its
usefulness depends on the provider, environment, task boundaries, and verification command; unattended execution is
not a guarantee of completion.

The record of attempts can help a later session understand what was tried and why it failed. That makes the recovery
process reviewable even when the agent needs human input or cannot complete the task.

### 3. Making Quality Criteria Explicit

Different reviews ask different questions. A security review examines exposure and trust boundaries; a performance
review examines expected load and bottlenecks; a test review checks whether acceptance criteria are exercised; a
writing review checks audience, clarity, and support for claims.

AIWG supplies specialist roles and workflows that separate these concerns, combine their findings, and record open
decisions. Phase gates can check whether the required artifacts and reviews are ready before the work advances.
Project policy determines who must approve a decision and which checks are required.

Multiple reviewers can still share an error. The practical benefit is a clearer review procedure and a saved account
of the findings, with tests or other independent checks where available.

---

## The Six Core Components

### 1. Memory — Structured Semantic Memory

The `.aiwg/` directory is a persistent artifact repository storing requirements, architecture decisions, test
strategies, risk registers, and deployment plans across sessions. Artifacts provide retrievable project knowledge that
can ground later work in recorded decisions and sources.

Artifacts can be referenced with `@-mentions` (e.g., `@.aiwg/requirements/UC-001-login.md`). Context sharing between
agents happens through artifacts: the requirements analyst writes use cases, the architecture designer reads them.

### 2. Reasoning — Multi-Agent Deliberation with Synthesis

AIWG provides specialist role definitions organized by domain. A workflow can route a complex artifact through the
reviewers the task requires:

```
Architecture Document Creation:
  1. Architecture Designer drafts SAD
  2. Review Panel (3-5 agents run in parallel):
     - Security Auditor    → threat perspective
     - Performance Engineer → scalability perspective
     - Test Architect       → testability perspective
     - Technical Writer     → clarity and consistency
  3. Documentation Synthesizer merges all feedback
  4. Human approval gate → accept, iterate, or escalate
```

Each reviewer receives a defined responsibility and relevant context. The synthesis should resolve duplicate or
conflicting findings, preserve uncertainty, and identify which conclusions were checked against sources or tests.
Parallel reviews require the corresponding provider capability and available task budget. Small bounded judgments
inside a workflow, such as a yes/no gate or a severity score, can go to [decision
support](#decision-support--bounded-decisions-offloaded-to-jev) instead of a full reasoning pass.

### 3. Learning — Closed-Loop Self-Correction (Agent Loop)

The agent loop executes tasks iteratively and uses verification results to guide the next attempt. Its task record can preserve
failure analysis and revised strategies for subsequent iterations.

```
Agent Loop Iteration:
  1. Execute task with current strategy
  2. Verify results (tests pass, lint clean, types check)
  3. If failure: analyze root cause → extract structured learning → adapt strategy
  4. Log iteration state (checkpoint for resume)
  5. Repeat within configured limits; stop or escalate when required
```

The external agent loop (`agent-loop-ext`) adds process tracking, session persistence, and recovery controls. For long-running work, define a time
or iteration budget and inspect the provider-specific recovery behavior; surviving a particular failure depends on how
the runner and host are configured.

### 4. Verification — Bidirectional Traceability

AIWG supports links between documentation and code so reviewers can inspect relationships and find drift:

```typescript
// src/auth/login.ts
/**
 * @implements @.aiwg/requirements/UC-001-login.md
 * @architecture @.aiwg/architecture/SAD.md#section-4.2
 * @tests @test/unit/auth/login.test.ts
 */
export function authenticateUser(credentials: Credentials): Promise<AuthResult> {
```

Verification can follow Doc → Code, Code → Doc, Code → Tests, and Citations → Sources. These relationships make claims
easier to inspect; they do not prove that implementation or citations are correct. Ask the workflow to report missing
targets, inconsistent behavior, and unsupported source claims.

### 5. Planning — Phase Gates with Cognitive Load Management

AIWG structures work using Cooper's Stage-Gate methodology (1990), breaking multi-month projects into bounded phases with explicit quality criteria and human approval:

```
Inception → Elaboration → Construction → Transition → Production
   LOM          ABM            IOC            PR
```

Phase structure gives a team bounded decisions and review points: establish goals during Inception, evaluate design
and risks during Elaboration, implement and verify during Construction, and prepare operational handoff during
Transition. Templates help make the expected outputs visible. The project determines which artifacts, reviewers, and
approval gates are appropriate; a small task need not use the full lifecycle.

### 6. Style — Controllable Voice Generation

Voice profiles describe writing preferences such as formality, technical depth, directness, examples, uncertainty, and
sentence variation. They give the assistant a reusable style specification that can be reviewed against the audience
and document purpose.

Built-in voices: `technical-authority` (docs, RFCs), `friendly-explainer` (tutorials), `executive-brief` (summaries),
and `casual-conversational` (blogs, social). Ask “Create a reusable voice profile from these writing samples” to
define your own.

---

## A Real Project Walkthrough

The following illustrative customer-portal project shows how ordinary prompts connect the components across a
lifecycle. These examples describe requests you can make, not a measured project outcome. The assistant discovers
the relevant procedures and reads their instructions before carrying out each request.

Start with a bounded goal, agree on acceptance criteria, and inspect the artifacts at each step. The time and review
effort depend on the project, source quality, tools, and decisions involved. Smaller changes can enter at the phase
that fits their current state rather than repeating the entire lifecycle.

### Inception

> Help me define a customer portal with real-time chat. Walk me through the goals, users, constraints, and acceptance criteria.

**Memory**: Intake forms capture goals, constraints, stakeholders in `.aiwg/intake/`
**Planning**: Executive Orchestrator guides through structured questionnaire
**Reasoning**: Requirements Analyst drafts initial use cases, Product Designer reviews UX
**Verification**: Requirements reference intake forms, ensuring alignment
**Human Gate**: Stakeholder reviews intake → approves transition to Elaboration

### Elaboration

> Review the approved intake, develop the architecture and test strategy, and identify the risks we need to resolve.

**Memory**: Architecture doc, ADRs, threat model, test strategy accumulate in `.aiwg/`
**Reasoning**: Multi-agent review panel — Architecture Designer drafts, Security Auditor + Performance Engineer + Test Architect critique in parallel, Documentation Synthesizer merges
**Learning**: The agent loop iterates on ADRs (generate options, evaluate against constraints, refine)
**Style**: Technical documents use `technical-authority`, stakeholder summaries use `executive-brief`
**Human Gate**: Architect reviews SAD, security team approves threat model

### Construction

> Turn the reviewed design into an implementation plan. Implement authentication, verify its acceptance criteria,
> and run the relevant tests.

**Learning**: The agent loop handles implementation iterations — execute, verify (run tests), learn ("async race condition in token refresh"), adapt (add synchronization), retry
**Verification**: Code references requirements (`@implements UC-001`), tests reference code
**Memory**: Test plans, implementation, deployment scripts accumulate across iterations
**Human Gate**: Code review approves merges, QA approves test results

### Transition

> Prepare the production rollout with monitoring and rollback. After the required release approval, deploy it and
> organize fourteen days of early-life support.

**Planning**: Deployment checklist — monitoring, rollback plan, incident response
**Learning**: Failed validation produces a diagnosis and a revised plan; retries follow the operation's recovery and
approval requirements
**Verification**: Deployment scripts reference architecture (which services, what order)
**Human Gate**: Operations team reviews deployment plan → approves production release

---

## Claims, Evaluation, and Evidence

Evaluate a workflow against the task it is meant to support. AIWG provides structures for review, traceability, and
recovery; it does not promise a fixed cost saving, perfect citations, or error-free execution.

| Capability to evaluate | Evidence to collect | Useful comparison |
|------------------------|---------------------|-------------------|
| Persistent project context | Whether a later session reads and applies a prior decision | The same kind of task with the team's usual handoff |
| Specialist review | Correct findings, missed issues, and reviewer effort | A comparable review using the existing process |
| Task recovery | Failure diagnosis, attempts, limits, and final verification | Similar failures handled without the loop |
| Citation checking | Source existence and support for each material claim | Manual source inspection |
| Structured planning | Completeness and usefulness of the resulting plan | The team's existing planning artifact |
| Cost and throughput | Model calls, elapsed time, and human review effort | Comparable tasks with the same acceptance criteria |

Research results from Agent Laboratory, self-consistency, tree search, and other systems inform the design. Their
percentages and benchmark scores are not measurements of AIWG. The [research foundations](#research-foundations) and
[reading list](docs/overview/reading-list.md) retain the underlying sources. The [executive
brief](docs/overview/executive-brief.md) describes a practical pilot.

---

## When to Use AIWG (and When Not To)

### Good Fit

Multi-week or multi-month projects where requirements evolve, multiple stakeholders have different concerns, quality gates are required, auditability matters, or context exceeds conversation limits.

**Examples**: New product features with architecture/security/operational implications, legacy system migrations requiring phased rollback strategies, research projects needing literature review and reproducibility, compliance-heavy domains (healthcare, finance, aerospace) needing audit trails.

### Not the Best Fit

A full lifecycle is usually unnecessary for a one-off question that needs no shared context, saved artifact, or
follow-up. A focused writing, lookup, or review capability can still be useful without introducing every phase and
gate.

**Examples**: "Write a Python script to parse this CSV," "Fix this typo," "Explain how this code works."

### The Trade-off

Match the workflow to the task. Use a bounded skill for a small result, a saved artifact when work needs to carry
forward, and a phase-based process when coordination and review warrant it. Additional context, reviewers, or
verification steps can add model calls and human effort; judge their value against the outcome you need.

```
User intent → AIWG CLI → Deploy agents + rules + templates → AI platform
                │                                                │
                ▼                                                ▼
         "aiwg use all --provider X"                  Claude Code / Copilot /
                │                                     Cursor / Warp / Factory /
                ▼                                  OpenCode / Codex / Devin Desktop
         ┌──────────────┐
         │ Agents       │  Specialized AI personas with domain expertise
         │ Commands     │  CLI + slash commands for workflow automation
         │ Skills       │  Natural language workflow triggers
         │ Rules        │  Enforcement patterns (security, quality, anti-laziness)
         │ Templates    │  SDLC artifact templates with progressive disclosure
         └──────────────┘
                │
                ▼
         .aiwg/ artifacts ← Persistent project memory across sessions
```

---

## How It Works

> For visual diagrams of AIWG's architecture, deploy flow, and discovery model, see [`docs/architecture-overview.md`](docs/architecture-overview.md). The prose walkthrough lives in [`docs/how-it-works.md`](docs/how-it-works.md).

**At a glance** — the deployment layer copies instructions into provider-readable locations, connects project context,
and reports verification. The provider loads those instructions. Optional runtime components, such as artifact
services or orchestration tools, perform additional work when configured and invoked.

```mermaid
flowchart LR
  subgraph Source["AIWG framework source"]
    direction TB
    KERN["Kernel skills<br/>within provider listing budgets"]
    STD["Standard skills<br/>read from $AIWG_ROOT"]
    AGENT["Specialist agents"]
    RULES["Workflow rules"]
    TPL["Artifact templates"]
  end

  CLI(["aiwg use all<br/>--provider X"]) --> DEPLOY

  subgraph DEPLOY["Deploy step (one-shot)"]
    direction TB
    COPY["Copy kernel skills, agents,<br/>rules to provider-native dirs"]
    INDEX["Build artifact index<br/>~/.local/share/aiwg/index/"]
    CTX["Emit AIWG.md + AGENTS.md<br/>at project root"]
  end

  Source --> CLI
  DEPLOY --> Project

  subgraph Project["Your project (after deploy)"]
    direction TB
    PLAT[".claude/skills/<br/>.codex/agents/<br/>.warp/agents/ ..."]
    AIWGMD["AIWG.md / .hermes.md /<br/>WARP.md / AGENTS.md"]
    ART[".aiwg/<br/>requirements/<br/>architecture/<br/>..."]
  end

  Project --> SESS

  subgraph SESS["AI session (Claude / Codex / Hermes / etc.)"]
    direction TB
    NATIVE["Platform-native loader<br/>reads provider dir"]
    DISC(["Assistant capability discovery<br/>+ asset lookup"])
  end

  classDef optional stroke-dasharray: 5 5,fill:#fef9e7
  class DISC optional
  class INDEX optional
```

**Multi-agent orchestration** — once deployed, AIWG coordinates specialized agents through phase-gated workflows:

```
You: "transition to elaboration phase"

AIWG: [Step 1] Requirements Analyst   → Analyze vision document, generate use case briefs
      [Step 2] Architecture Designer  → Baseline architecture, identify technical risks     } parallel
      [Step 3] Security Architect     → Threat model, security requirements                 }
      [Step 4] Documentation Synth.   → Merge reviews into Architecture Baseline Milestone
      [Step 5] Human Gate             → GO / CONDITIONAL_GO / NO_GO decision
      [Step 6] → Next phase or iterate
```

The orchestration pattern: **Primary Author → Parallel Reviewers → Synthesizer → Human Gate → Archive**. Agents run in parallel where possible, with human-in-the-loop checkpoints at phase transitions.

---

## Features

- **Specialist agents** — roles for architecture, implementation, testing, security, cloud, data engineering,
  research, content, and operations.
- **Workflow skills and commands** — discoverable procedures for reviews, intake, research, curation, planning, and delivery.
- **Rules and review criteria** — instructions for preserving work, handling sensitive configuration, checking claims,
  and reporting verification.
- **Artifact templates** — structured requirements, design decisions, campaign briefs, source notes, runbooks, and
  review reports.
- **Multi-provider deployment** — Google Antigravity CLI, Claude Code, OpenAI Codex, GitHub Copilot, Cursor, DeepSeek
  Harness, Factory AI, Flue (experimental), Grok Bot, Grok Build, Hermes, Muse Code, OpenCode, OpenClaw, OpenHuman, Pi Coding Agent, Oh My
  Pi, Warp Terminal, and Devin Desktop.
- **Domain frameworks** — software development, forensics, marketing, research, media curation, operations, knowledge
  base, and security engineering.
- **Dataset workflows** — assessment, indexing, lineage, synchronization, and retirement through dataset intelligence;
  the separate [`aiwg-training`](https://github.com/jmagly/aiwg-training) project covers training-data curation and
  exports.
- **Memory addons** — compound memory, line memory, wiki-oriented knowledge, and artifact lookup for different
  persistence needs.
- **Writing and voice tools** — reusable voice profiles, context-sensitive diagnostics, revision workflows, and
  alternatives for content generation.
- **Testing quality** — test conformance, reversible normalization, mutation testing, and flaky-test review.
  See the [AIWG test conformance example](docs/conformance-aiwg-example.md) for reviewed source controls
  and runner evidence.
- **Decision support** — optional offload of bounded decisions (yes/no gates, a pick from known options, severity
  scores) to Jev, with a typed answer, a confidence score, and a fallback to the assistant's own reasoning.
- **Agent loops** — bounded execution, failure analysis, checkpoints, and supported process recovery.
- **RLM** — recursive context decomposition for tasks whose source material needs to be divided into smaller working sets.
- **YAML metalanguage** — structured workflow and artifact definitions with schema-oriented validation.
- **MCP integration** — tools and resources exposed through configured servers and provider connections.
- **Traceability and provenance** — relationships between requirements, code, tests, sources, and generated artifacts.
- **Session history and diagnostics** — import, search, and inspect prior AI work across providers, check deployment
  health, and diagnose provider wiring.
- **Project-local extensions and marketplace delivery** — keep custom instructions with the project and package
  reusable capabilities through the appropriate distribution path.

The [framework and addon catalog](#what-you-get) below describes these capabilities in more detail. Compatibility and
execution requirements are explicit in the [provider inventory](docs/providers/provider-inventory.md) and [CLI
reference](docs/cli/reference.md).

---

## Quick Start

> **Prerequisites:** Node.js >=24 and an AI platform (Claude Code, GitHub Copilot, Cursor, Warp Terminal, or others). See [Prerequisites Guide](docs/getting-started/prerequisites.md) for details.

> **Release verification:** Inspect the provenance and signature material for the release you install. The
[verification guide](docs/releases/verifying.md) describes the available artifacts and commands.

### Install & Deploy

The prompt-led installer at the top of this README is the canonical beginner path. For manual setup:

```bash
npm i -g aiwg
cd /path/to/your/project
aiwg use all --provider claude   # replace claude with your provider selector
```

Deployment refreshes the shared context and reports verification and any required reload. Follow that result, then ask
the agent to check the intended project and its AIWG connection. The [manual installation
reference](docs/cli/install-and-repair.md) covers the terminal path in detail.

For a deliberately narrower deployment, choose the relevant framework or addon instead of `all`. These are
alternatives, not a sequence of required setup steps:

```bash
aiwg use sdlc --provider claude          # Software development
aiwg use forensics --provider claude     # Investigation workflows
aiwg use marketing --provider claude     # Campaign and content work
aiwg use media-curator --provider claude # Media collections
aiwg use research --provider claude      # Research artifacts
aiwg use civic-action --provider claude  # Civic review and preparation
aiwg use rlm --provider claude           # Context decomposition
```

For maintenance or an existing workspace that needs context migration, preview the relevant regeneration branch rather
than treating every branch as installation:

> Preview how to refresh this workspace’s provider context. If it needs existing-project extraction or migration,
> explain the proposed changes, preserve project-specific instructions, and verify the result.

The [regeneration guide](docs/regenerate-guide.md) also covers canonical refresh and legacy compatibility. Use the
branch that matches the workspace state. To scaffold a new project rather than connect the current one, see the
[new-project guide](docs/getting-started/new-project.md).

### Get a First Useful Result

After setup, ask your agent:

```text
Use AIWG to review this project's README for unclear positioning and missing
onboarding steps. Save a report at
.aiwg/marketing/brand/audit/readme-review.md with file references and the
three highest-priority fixes. Leave the README unchanged.
```

Open the report and check the source references, reader impact, and proposed fixes. In a later session, ask the agent
to read that report and implement the first agreed change. The [first-result
walkthrough](docs/getting-started/just-try-it.md) includes an illustrative finding and alternative tasks. Setup
readiness is the prerequisite; a useful artifact is what lets you assess the workflow.

### Customize Without Forking

Author project-specific rules, skills, agents, addons, or frameworks
directly under `.aiwg/{extensions,addons,frameworks}/<name>/`. Use
`.aiwg/plugins/<name>/` only when you are wrapping a bundle for marketplace
delivery. No fork, no rebuild. Discovered automatically by `aiwg use`.

> Create a project-local extension named my-team-rules with a starter rule. Deploy it here, check its health, and
> help me prepare it for upstream promotion once it is proven.

The bundle is **byte-identical** in shape to its upstream form, so
promotion uses a hash-verified copy with zero rewrite. See the
[customization guide](docs/customization/README.md) for the three paths
(project-local, fork, corpus).

### Claude Code Marketplace (Alternative)

> Add the AIWG marketplace to Claude Code and install the SDLC, Agent Loop, and Compound Memory plugins.

The marketplace contains independently packaged framework and addon
plugins, so you can install only the capabilities a Claude Code workspace
needs. Source-distributed opt-in addons such as Civic Action deploy with
`aiwg use civic-action` and do not imply a marketplace wrapper.

### Multi-Platform Deployment

```bash
aiwg use all --provider antigravity    # Google Antigravity CLI (alias: agy)
aiwg use all --provider claude         # Claude Code
aiwg use all --provider codex          # OpenAI Codex
aiwg use all --provider copilot        # GitHub Copilot
aiwg use all --provider cursor         # Cursor
aiwg use all --provider dsh            # DeepSeek Harness
aiwg use all --provider factory        # Factory AI
aiwg use all --provider grokbot        # Grok Bot
aiwg use all --provider grok-build     # Grok Build
aiwg use all --provider opencode       # OpenCode
aiwg use all --provider warp           # Warp Terminal
aiwg use all --provider devin          # Devin Desktop
aiwg use all --provider openclaw       # OpenClaw
aiwg use all --provider hermes         # Hermes
aiwg use all --provider openhuman      # OpenHuman
aiwg use all --provider pi             # Pi Coding Agent
aiwg use all --provider omp            # Oh My Pi
aiwg use all --provider muse           # Muse Code
```

`all` means the complete deployable end-user surface. It intentionally omits
contributor-only development bundles and packages that cannot be deployed
directly.

### First-Party Integrators

AIWG can also be distributed through another runtime. Check the integrator's version and included assets before
assuming that its bundled surface matches a standalone AIWG install. Follow that runtime's setup instructions, then
verify the project connection.

| Partner | Install | What you get |
|---------|---------|--------------|
| **[Omnius](https://www.npmjs.com/package/omnius)** | `npm i -g omnius` | An integration path for AIWG assets in an autonomous coding runtime. Consult the package documentation for the bundled version, supported asset surface, and setup requirements. |

If you ship a product that bundles AIWG and want to be listed here, open an issue at https://github.com/jmagly/aiwg/issues.

---

## What You Get

AIWG installs reusable context, specialist agents, workflow skills, rules, and
artifact templates into the AI tools your team already uses. This fragment keeps
the older README's broad inventory shape while updating claims against the
current repository. Counts shown in framework rows are source-file counts from
this working tree; addon rows omit totals because several addons expose
capabilities through manifests, docs, scripts, or nested skill packages.

### Frameworks

| Framework | Source Snapshot | What It Helps You Do |
|-----------|-----------------|----------------------|
| **[SDLC Complete](agentic/code/frameworks/sdlc-complete/)** | 100 agents, 116 skills, 217 templates, 39 rules, 12 commands, 8 flows | Run a full software delivery lifecycle from intake through transition with phase gates, planning artifacts, implementation support, test strategy, deployment handoff, and maintenance workflows |
| **[Forensics Complete](agentic/code/frameworks/forensics-complete/)** | 13 agents, 20 skills, 12 templates, 4 rules | Preserve and analyze incident evidence through scoping, triage, acquisition, log review, persistence hunting, timeline building, IOC extraction, and reporting |
| **[Media/Marketing Kit](agentic/code/frameworks/media-marketing-kit/)** | 38 agents, 34 skills, 97 templates, 2 flows | Plan, produce, review, publish, and analyze marketing campaigns with reusable briefs, brand/legal gates, channel assets, and performance artifacts |
| **[Media Curator](agentic/code/frameworks/media-curator/)** | 6 agents, 21 skills | Assess mixed media collections, research sources, acquire approved material, tag metadata, verify integrity, create transcript sidecars, and prepare exports or research handoffs |
| **[Research Complete](agentic/code/frameworks/research-complete/)** | 8 agents, 41 skills, 16 templates | Turn literature searches and PDFs into reviewable research artifacts: source records, grounded summaries, citation work, GRADE/FAIR-style quality checks, gap notes, and provenance |
| **[Knowledge Base](agentic/code/frameworks/knowledge-base/)** | 3 skills, 5 templates | Build a linked AI-assisted wiki from loose sources, notes, entities, concepts, comparisons, and synthesis pages without forcing formal literature-review overhead |
| **[Ops Complete](agentic/code/frameworks/ops-complete/)** | 12 agents, 1 skill, 17 templates, 6 rules | Convert operational procedures into executable runbooks, inventories, incident reports, troubleshooting trees, and extension-backed ops workflows |
| **[Security Engineering](agentic/code/frameworks/security-engineering/)** | 2 agents, 27 skills, 7 templates, 13 rules | Make applied security decisions for crypto primitives, chains of trust, auth factors, degraded modes, runtime secrets, supply-chain trust, physical threats, and DFIR readiness |
| **[Validation Complete](agentic/code/frameworks/validation-complete/)** | 1 skill | Add focused validation workflow support where a project needs reviewable checks without adopting a full lifecycle framework |

Start with [Install, Connect, and Verify](docs/getting-started/install-connect-verify.md),
then deploy a framework with `aiwg use <framework>`. The [capability reference](docs/cli/reference.md)
lists the current framework names accepted by the CLI.

### Addons

| Addon | What It Helps You Do |
|-------|----------------------|
| **[AIWG Utils](agentic/code/addons/aiwg-utils/)** | Shared rules, discovery helpers, regeneration support, mention tooling, workspace maintenance, and stewardship primitives used across AIWG |
| **[Agent Loop](agentic/code/addons/agent-loop/)** | Run bounded iterative agent loops with recovery, reflection, completion tracking, and resumable progress tracking |
| **[RLM](agentic/code/addons/rlm/)** | Decompose large codebases or document corpora into smaller reviewed slices through recursive planning and subtask execution |
| **[Composition Engine](agentic/code/addons/composition-engine/)** | Define and validate provider-neutral Flow graph contracts for composed workflows |
| **[Decision Engine](agentic/code/addons/decision-engine/)** | Offload bounded decisions to Jev or an LLM-subagent binding through normalized rulesets, with typed answers, confidence, and fallback; opt-in and not part of `aiwg use all` |
| **[Graph Pattern](agentic/code/addons/graph-pattern/)** | Add an optional graph-oriented profile over AIWG Flow for conditional routes, reducers, and graph validation |
| **[Orchestration Topology Lab](agentic/code/addons/orchestration-topology-lab/)** | Compare single-agent, bounded-parallel, and planner-worker orchestration topologies using local fixtures and explicit evidence |
| **[Guided Implementation](agentic/code/addons/guided-implementation/)** | Keep issue-to-code work inside a bounded retry loop with validation after each attempt and structured escalation when needed |
| **[Daemon](agentic/code/addons/daemon/)** | Run opt-in persistent session support for background tasks, queues, health checks, and scheduler integration |
| **[Agentic Installer](agentic/code/addons/agentic-installer/)** | Use `setup.aiwg.io/v1` SetupManifest files for reproducible, agent-driven install workflows with recovery paths |
| **[AIWG Dev](agentic/code/addons/aiwg-dev/)** | Scaffold and validate AIWG source packages, skills, agents, commands, and rules; install explicitly for contributor work |
| **[Skill Factory](agentic/code/addons/skill-factory/)** | Build, enhance, validate, and package skills through a dedicated skill-authoring workflow |
| **[AIWG Evals](agentic/code/addons/aiwg-evals/)** | Run agent and workflow evaluation patterns with explicit benchmark inputs and quality scoring |
| **[Monitorability Red Team](agentic/code/addons/monitorability-red-team/)** | Exercise synthetic local fixtures that expose multi-agent monitoring limits and evidence blind spots |
| **[Long-Context Bench](agentic/code/addons/long-context-bench/)** | Benchmark compressed skim plus exact recovery against current context baselines |
| **[Natural-Language Harness](agentic/code/addons/natural-language-harness/)** | Map inspectable natural-language policy documents to deterministic AIWG mechanisms and ablation reports |
| **[Premortem v2](agentic/code/addons/premortem-v2/)** | Generate, select, and independently verify bounded risk sets before execution |
| **[Century Readiness](agentic/code/addons/century-readiness/)** | Review long-horizon stewardship, degradation, replacement, evidence, and meaning-preservation risks |
| **[Dataset Intelligence](agentic/code/addons/dataset-intelligence/)** | Route dataset intake, planning, materialization, traceability, verification, export, synchronization, and retirement through governed workflows |
| **[Schema Governance](agentic/code/addons/schema-governance/)** | Discover, author, validate, evolve, and normalize schemas across datasets and SDLC artifacts |
| **[Compound Memory](agentic/code/addons/compound-memory/)** | Govern promotion from raw evidence and session candidates into line memory or linked wiki knowledge with lineage |
| **[Line Memory](agentic/code/addons/line-memory/)** | Keep a bounded plain-text set of durable project facts with recency retention and reviewed lifecycle operations |
| **[LLM Wiki](agentic/code/addons/llm-wiki/)** | Maintain a Markdown wiki topology for entities, concepts, sources, comparisons, and syntheses |
| **[Semantic Memory](agentic/code/addons/semantic-memory/)** | Provide topology-agnostic memory operations for ingest, lint, query/capture, and event logging |
| **[Auto Memory](agentic/code/addons/auto-memory/)** | Seed Claude Code Automatic Memory files with AIWG-aware testing, debugging, and architecture sections |
| **[Agent Persistence](agentic/code/addons/agent-persistence/)** | Supply reusable human-in-the-loop gate definitions for destructive actions, overrides, and recovery escalation |
| **[AIWG Hooks](agentic/code/addons/aiwg-hooks/)** | Provide hook templates for workflow tracing, permissions, session management, context injection, and quality gates |
| **[AIWG Fleet](agentic/code/addons/aiwg-fleet/)** | Apply quiet-bot, mention-only participation, and small-plan cost-discipline policies across multi-project fleets |
| **[Browser Control](agentic/code/addons/browser-control/)** | Drive a user-authorized Chromium-derived browser through Playwright MCP with allow-list and audit boundaries |
| **[Droid Bridge](agentic/code/addons/droid-bridge/)** | Bridge Claude Code to Factory Droid for batch operations and automated fixes through MCP |
| **[MCP/UAT Toolkit](agentic/code/addons/uat-mcp/)** | Generate, execute, and report user-acceptance tests against MCP tool surfaces |
| **[Civic Action](agentic/code/addons/civic-action/)** | Prepare evidence-bound civic research, public-records planning, meeting review, local-resource profiles, corrections, and publication review |
| **[Network Analysis](agentic/code/addons/network-analysis/)** | Governed saved-PCAP/PCAPNG analysis with bounded TShark recipes, cited packet evidence, and optional local Termshark review |
| **[Testing Quality](agentic/code/addons/testing-quality/)** | Assess test conformance, normalize suites with reversible plans, and add TDD, mutation, flaky-test, and factory workflows |
| **[Writing Quality](agentic/code/addons/writing-quality/)** | Review editorial quality, author requirements, and voice consistency without treating heuristic scores as authorship proof |
| **[Voice Framework](agentic/code/addons/voice-framework/)** | Define, analyze, blend, and apply reusable writing voice profiles and runtime-selectable output modes |
| **[Color Palette](agentic/code/addons/color-palette/)** | Generate and review accessible color palettes using color theory, trend research, and WCAG checks |
| **[Doc Intelligence](agentic/code/addons/doc-intelligence/)** | Scrape, extract, split, audit, and synchronize documentation sources |
| **[Prose Integration](agentic/code/addons/prose-integration/)** | Detect, read, validate, wire, and run OpenProse contract programs in supported AIWG sessions |
| **[NLP Prod](agentic/code/addons/nlp-prod/)** | Design and productionize LLM inference pipelines with eval-first, pattern-guided workflow support |
| **[Context Curator](agentic/code/addons/context-curator/)** | Filter distractors and curate context packs for agent work where irrelevant material can derail results |
| **[Twelve-Factor](agentic/code/addons/twelve-factor/)** | Review or design applications against Twelve-Factor and modern cloud-native criteria |
| **[Verbalized Sampling](agentic/code/addons/verbalized-sampling/)** | Apply and evaluate verbalized probability-distribution prompting for output diversity experiments |
| **[Star Prompt](agentic/code/addons/star-prompt/)** | Offer a tasteful repository-star prompt after successful command completion |

Addon details live in each source directory and, where public docs exist, under
`docs/addons/`. Use [Key Addons](docs/getting-started/key-addons.md) for a
guided end-user selection path.

---

### Agents

Specialized AI personas deploy to your platform with defined responsibilities,
tools, and operating rhythms. The exact inventory changes as frameworks evolve,
so this README keeps durable groupings and examples instead of relying on one
global total.

#### SDLC Agents

| Domain | Examples |
|--------|----------|
| **Testing & Quality** | Test Engineer, Test Architect, Mutation Analyst, Regression Analyst, Reliability Engineer |
| **Security & Compliance** | Security Auditor, Security Architect, Compliance Checker, Privacy Officer, Citation Verifier |
| **Architecture & Design** | Architecture Designer, API Designer, Cloud Architect, System Analyst, Product Designer, Decision Matrix Expert |
| **DevOps & Cloud** | AWS Specialist, Azure Specialist, GCP Specialist, Kubernetes Expert, DevOps Engineer, Multi-Cloud Strategist |
| **Backend & Data** | Django Expert, Spring Boot Expert, Data Engineer, Database Optimizer, Software Implementer, Incident Responder |
| **Frontend & Mobile** | React Expert, Frontend Specialist, Mobile Developer, Accessibility Specialist, UX Lead |
| **AI/ML & Performance** | AI/ML Engineer, Performance Engineer, Cost Optimizer, Metrics Analyst |
| **Code Quality** | Code Reviewer, Debugger, Dead Code Analyzer, Technical Debt Analyst, Legacy Modernizer |
| **Documentation** | Technical Writer, Documentation Synthesizer, Documentation Archivist, Context Librarian |
| **Requirements & Planning** | Requirements Analyst, Requirements Reviewer, Intake Coordinator, RACI Expert |
| **Agent/Tool Smiths** | AgentSmith, CommandSmith, MCPSmith, SkillSmith, ToolSmith |
| **Governance & Meta** | Executive Orchestrator, Recovery Orchestrator, Migration Planner |

#### Forensics Agents

| Agent | What It Does |
|-------|-------------|
| Forensics Orchestrator | Coordinates investigation scope, evidence handling, analysis, and reporting |
| Triage Agent | Captures volatile data following evidence-priority guidance |
| Acquisition Agent | Collects evidence with chain-of-custody and hash verification |
| Log Analyst | Reviews auth, syslog, journal, and application logs for suspicious activity |
| Persistence Hunter | Checks cron, systemd, SSH keys, LD_PRELOAD, PAM modules, and kernel-module indicators |
| Container Analyst | Reviews Docker, containerd, and Kubernetes evidence |
| Network Analyst | Reviews connection state, DNS, beaconing, and exfiltration indicators |
| Memory Analyst | Supports Volatility-style memory forensics workflows |
| Cloud Analyst | Reviews AWS, Azure, and GCP audit trails and IAM posture |
| Timeline Builder | Correlates events into chronological incident timelines |
| IOC Analyst | Extracts and formats indicators for downstream response |
| Recon Agent | Builds a target baseline for authorized investigation |
| Reporting Agent | Produces structured executive and technical investigation reports |

#### Marketing Agents

| Domain | Examples |
|--------|----------|
| **Strategy** | Campaign Strategist, Brand Guardian, Positioning Specialist, Market Researcher, Content Strategist, Channel Strategist |
| **Creation** | Copywriter, Content Writer, Email Marketer, Social Media Specialist, SEO Specialist, Graphic Designer, Art Director |
| **Management** | Campaign Orchestrator, Production Coordinator, Traffic Manager, Asset Manager, Workflow Coordinator |
| **Analytics** | Marketing Analyst, Data Analyst, Attribution Specialist, Reporting Specialist, Budget Planner |
| **Communications** | PR Specialist, Crisis Communications, Corporate Communications, Internal Communications, Media Relations |

#### Other Framework Agents

Research uses discovery, acquisition, documentation, citation, quality,
archival, provenance, and workflow roles. Media Curator uses discography/source,
acquisition, quality, metadata, and completeness roles. Ops Complete adds
runbook execution and inventory roles. Security Engineering adds security
specialists for applied security decisions and supply-chain review.

---

### Rules

Rules are durable guardrails that deploy with the frameworks or addons that own
them. They prevent common agent failure modes and define review boundaries.

#### Core Rules

| Rule | Severity | What It Enforces |
|------|----------|-----------------|
| `no-attribution` | CRITICAL | AI tools are tools; do not add AI attribution to commits, PRs, docs, or code |
| `token-security` | CRITICAL | Keep tokens and secrets out of source; use scoped lifetime and restricted file permissions |
| `versioning` | CRITICAL | Use the repository's CalVer release format consistently |
| `citation-policy` | CRITICAL | Do not fabricate citations, DOIs, URLs, or research claims |
| `anti-laziness` | HIGH | Do not delete tests, skip required checks, remove features, or weaken assertions to pass |
| `executable-feedback` | HIGH | Run appropriate validation before returning implementation work |
| `failure-mitigation` | HIGH | Detect and recover from hallucination, context loss, instruction drift, safety, technical, and consistency failures |
| `research-before-decision` | HIGH | Inspect the codebase and docs before making technical decisions |
| `instruction-comprehension` | HIGH | Parse prohibitions, requirements, and preferences before acting |
| `subagent-scoping` | HIGH | Keep delegated tasks focused and bounded when delegation is used |

#### Domain Rules

| Domain | Examples |
|--------|----------|
| **SDLC** | HITL gates

Node.js（README 徽章标注 ≥24，实际范围待核验）；npm 全局安装权限（macOS 可能需处理 EACCES）；一个受支持的 AI 提供方（如 claude、codex、copilot、cursor、omp、pi，完整名单待核验）；可选原生特性需单独启用；Cockpit/Agentic Sandbox 需 Docker 或 KVM/libvirt，具体前置待核验；模型与 API Key 由所用提供方决定，AIWG 未说明自带密钥；费用、境外依赖与国内网络可用性待核验。