Skip to content
Back to search

aiwg

AIWG - Modular agentic framework for SDLC, marketing automation, and workflow orchestration. 200+ agents, 67+ CLI commands, 400+ deployable agent/skill/command/rule artifacts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jmagly--aiwg/badge.svg)](/listings/jmagly--aiwg)

HTML

<a href="/listings/jmagly--aiwg"><img src="/api/listings/jmagly--aiwg/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

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:

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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 702 lines
  1. {
  2. "name": "aiwg",
  3. "owner": {
  4. "name": "AIWG Contributors",
  5. "email": "support@aiwg.io"
  6. },
  7. "description": "AIWG - Modular agentic framework for SDLC, marketing automation, and workflow orchestration. 200+ agents, 67+ CLI commands, 400+ deployable agent/skill/command/rule artifacts.",
  8. "version": "2026.11.8",
  9. "plugins": [
  10. {
  11. "name": "sdlc",
  12. "source": "./agentic/code/plugins/sdlc",
  13. "description": "Complete SDLC framework with 180+ specialized agents for software development lifecycle management.",
  14. "version": "2026.11.8",
  15. "author": {
  16. "name": "AIWG Contributors"
  17. },
  18. "license": "MIT",
  19. "category": "productivity",
  20. "keywords": []
  21. },
  22. {
  23. "name": "marketing",
  24. "source": "./agentic/code/plugins/marketing",
  25. "description": "Marketing automation framework with 37 specialized agents for campaign management.",
  26. "version": "2026.11.8",
  27. "author": {
  28. "name": "AIWG Contributors"
  29. },
  30. "license": "MIT",
  31. "category": "productivity",
  32. "keywords": []
  33. },
  34. {
  35. "name": "voice",
  36. "source": "./agentic/code/plugins/voice",
  37. "description": "Voice profile system for consistent, authentic writing.",
  38. "version": "2026.11.8",
  39. "author": {
  40. "name": "AIWG Contributors"
  41. },
  42. "license": "MIT",
  43. "category": "productivity",
  44. "keywords": []
  45. },
  46. {
  47. "name": "writing",
  48. "source": "./agentic/code/plugins/writing",
  49. "description": "Writing quality validation and AI pattern detection.",
  50. "version": "2026.11.8",
  51. "author": {
  52. "name": "AIWG Contributors"
  53. },
  54. "license": "MIT",
  55. "category": "productivity",
  56. "keywords": []
  57. },
  58. {
  59. "name": "utils",
  60. "source": "./agentic/code/plugins/utils",
  61. "description": "Core AIWG utilities for context regeneration and workspace management.",
  62. "version": "2026.11.8",
  63. "author": {
  64. "name": "AIWG Contributors"
  65. },
  66. "license": "MIT",
  67. "category": "productivity",
  68. "keywords": []
  69. },
  70. {
  71. "name": "forensics",
  72. "source": "./agentic/code/plugins/forensics",
  73. "description": "Digital forensics and incident response framework with 14 specialized agents covering target profiling, evidence acquisition, log/memory/container/cloud analysis, IOC extraction, and reporting.",
  74. "version": "2026.11.8",
  75. "author": {
  76. "name": "AIWG Contributors"
  77. },
  78. "license": "MIT",
  79. "category": "productivity",
  80. "keywords": []
  81. },
  82. {
  83. "name": "security-engineering",
  84. "source": "./agentic/code/plugins/security-engineering",
  85. "description": "Applied security framework for cryptographic primitive selection, chain-of-trust design, authentication factor analysis, supply-chain trust, and physical-threat modeling. Complements OWASP-style application audits.",
  86. "version": "2026.11.8",
  87. "author": {
  88. "name": "AIWG Contributors"
  89. },
  90. "license": "MIT",
  91. "category": "productivity",
  92. "keywords": []
  93. },
  94. {
  95. "name": "research",
  96. "source": "./agentic/code/plugins/research",
  97. "description": "Research workflow framework with 9 specialized agents for discovery, acquisition, synthesis, citation management, GRADE quality assessment, and OAIS-compliant archival.",
  98. "version": "2026.11.8",
  99. "author": {
  100. "name": "AIWG Contributors"
  101. },
  102. "license": "MIT",
  103. "category": "productivity",
  104. "keywords": []
  105. },
  106. {
  107. "name": "media-curator",
  108. "source": "./agentic/code/plugins/media-curator",
  109. "description": "Media archive management framework with 7 specialized agents for source discovery, acquisition (yt-dlp / Internet Archive / Bandcamp), quality assessment, metadata tagging, and provenance tracking.",
  110. "version": "2026.11.8",
  111. "author": {
  112. "name": "AIWG Contributors"
  113. },
  114. "license": "MIT",
  115. "category": "productivity",
  116. "keywords": []
  117. },
  118. {
  119. "name": "ops",
  120. "source": "./agentic/code/plugins/ops",
  121. "description": "Operational infrastructure framework with 12 specialized agents covering incident response, runbook execution, fleet inventory, certificate lifecycle, and disaster recovery planning.",
  122. "version": "2026.11.8",
  123. "author": {
  124. "name": "AIWG Contributors"
  125. },
  126. "license": "MIT",
  127. "category": "productivity",
  128. "keywords": []
  129. },
  130. {
  131. "name": "knowledge-base",
  132. "source": "./agentic/code/plugins/knowledge-base",
  133. "description": "Knowledge-base / wiki framework with skills for ingestion, query, and lint. Build a structured, citable corpus with cross-references and concept pages.",
  134. "version": "2026.11.8",
  135. "author": {
  136. "name": "AIWG Contributors"
  137. },
  138. "license": "MIT",
  139. "category": "productivity",
  140. "keywords": []
  141. },
  142. {
  143. "name": "hooks",
  144. "source": "./agentic/code/plugins/hooks",
  145. "description": "Claude Code hooks for workflow tracing and observability.",
  146. "version": "2026.11.8",
  147. "author": {
  148. "name": "AIWG Contributors"
  149. },
  150. "license": "MIT",
  151. "category": "productivity",
  152. "keywords": []
  153. },
  154. {
  155. "name": "validation-complete",
  156. "source": "./agentic/code/plugins/validation-complete",
  157. "description": "Validation Complete for AIWG",
  158. "version": "2026.11.8",
  159. "author": {
  160. "name": "AIWG Contributors"
  161. },
  162. "license": "MIT",
  163. "category": "productivity",
  164. "keywords": []
  165. },
  166. {
  167. "name": "agent-loop",
  168. "source": "./agentic/code/plugins/agent-loop",
  169. "description": "Iterative AI coding loops with automatic recovery - iteration beats perfection",
  170. "version": "2026.11.8",
  171. "author": {
  172. "name": "AIWG Contributors"
  173. },
  174. "license": "MIT",
  175. "category": "productivity",
  176. "keywords": [
  177. "al",
  178. "agent-loop",
  179. "ralph",
  180. "iteration",
  181. "loop",
  182. "autonomous",
  183. "batch",
  184. "refactor",
  185. "migration"
  186. ]
  187. },
  188. {
  189. "name": "agent-persistence",
  190. "source": "./agentic/code/plugins/agent-persistence",
  191. "description": "Human-in-the-loop (HITL) gate definitions for agent operations. Provides reusable YAML gates for destructive-action authorization, false-positive override, and recovery escalation. Loaded by agent loops and orchestrators that need bounded human checkpoints.",
  192. "version": "2026.11.8",
  193. "author": {
  194. "name": "AIWG Contributors"
  195. },
  196. "license": "MIT",
  197. "category": "productivity",
  198. "keywords": [
  199. "hitl",
  200. "gates",
  201. "authorization",
  202. "human-in-the-loop",
  203. "agent-persistence",
  204. "escalation",
  205. "destructive-action"
  206. ]
  207. },
  208. {
  209. "name": "agentic-installer",
  210. "source": "./agentic/code/plugins/agentic-installer",
  211. "description": "Structured YAML manifests for reproducible, agent-driven software installation across platforms. Scripts are the primary artifact; agentic instructions handle adaptation and recovery.",
  212. "version": "2026.11.8",
  213. "author": {
  214. "name": "AIWG Contributors"
  215. },
  216. "license": "MIT",
  217. "category": "productivity",
  218. "keywords": [
  219. "installer",
  220. "setup",
  221. "agentic",
  222. "cross-platform",
  223. "scripts",
  224. "manifest"
  225. ]
  226. },
  227. {
  228. "name": "aiwg-evals",
  229. "source": "./agentic/code/plugins/aiwg-evals",
  230. "description": "Automated evaluation framework for agent quality, based on KAMI benchmark methodology and ReAct patterns",
  231. "version": "2026.11.8",
  232. "author": {
  233. "name": "AIWG Contributors"
  234. },
  235. "license": "MIT",
  236. "category": "productivity",
  237. "keywords": [
  238. "aiwg",
  239. "evals",
  240. "testing",
  241. "quality",
  242. "benchmark",
  243. "kami",
  244. "react"
  245. ]
  246. },
  247. {
  248. "name": "aiwg-dev",
  249. "source": "./agentic/code/plugins/aiwg-dev",
  250. "description": "Developer tooling for building AIWG itself and AIWG addons/frameworks. Not for end users — install explicitly with `aiwg use aiwg-dev`.",
  251. "version": "2026.11.8",
  252. "author": {
  253. "name": "AIWG Contributors"
  254. },
  255. "license": "MIT",
  256. "category": "productivity",
  257. "keywords": [
  258. "aiwg",
  259. "development",
  260. "validation",
  261. "contributor",
  262. "devtools",
  263. "scaffolding"
  264. ]
  265. },
  266. {
  267. "name": "auto-memory",
  268. "source": "./agentic/code/plugins/auto-memory",
  269. "description": "Automatic memory seed templates for AIWG projects",
  270. "version": "2026.11.8",
  271. "author": {
  272. "name": "AIWG Contributors"
  273. },
  274. "license": "MIT",
  275. "category": "productivity",
  276. "keywords": [
  277. "memory",
  278. "learning",
  279. "context",
  280. "scaffolding",
  281. "claude-code"
  282. ]
  283. },
  284. {
  285. "name": "browser-control",
  286. "source": "./agentic/code/plugins/browser-control",
  287. "description": "Drive a real, user-installed Chromium-derived browser from an AIWG agent. Wraps @playwright/mcp with a setup wizard, health-check doctor, allow-list enforcement, and an opinionated agent persona that respects authorization and audit boundaries.",
  288. "version": "2026.11.8",
  289. "author": {
  290. "name": "AIWG Contributors"
  291. },
  292. "license": "MIT",
  293. "category": "productivity",
  294. "keywords": [
  295. "browser",
  296. "playwright",
  297. "playwright-mcp",
  298. "automation",
  299. "authentication",
  300. "extension",
  301. "chromium",
  302. "chrome",
  303. "edge",
  304. "cdp",
  305. "browser-extension"
  306. ]
  307. },
  308. {
  309. "name": "color-palette",
  310. "source": "./agentic/code/plugins/color-palette",
  311. "description": "Color palette selection and review tooling with color theory fundamentals, current trend research, and accessibility analysis.",
  312. "version": "2026.11.8",
  313. "author": {
  314. "name": "AIWG Contributors"
  315. },
  316. "license": "MIT",
  317. "category": "productivity",
  318. "keywords": [
  319. "color",
  320. "palette",
  321. "design",
  322. "accessibility",
  323. "color-theory",
  324. "trends",
  325. "wcag"
  326. ]
  327. },
  328. {
  329. "name": "context-curator",
  330. "source": "./agentic/code/plugins/context-curator",
  331. "description": "Context curation and distractor filtering for production-grade agent reliability",
  332. "version": "2026.11.8",
  333. "author": {
  334. "name": "AIWG Contributors"
  335. },
  336. "license": "MIT",
  337. "category": "productivity",
  338. "keywords": []
  339. },
  340. {
  341. "name": "compound-memory",
  342. "source": "./agentic/code/plugins/compound-memory",
  343. "description": "Governed orchestration across AIWG line memory, semantic memory, and llm-wiki.",
  344. "version": "2026.11.8",
  345. "author": {
  346. "name": "AIWG Contributors"
  347. },
  348. "license": "MIT",
  349. "category": "productivity",
  350. "keywords": [
  351. "memory",
  352. "compound-memory",
  353. "line-memory",
  354. "llm-wiki",
  355. "semantic-memory",
  356. "persistent-context"
  357. ]
  358. },
  359. {
  360. "name": "daemon",
  361. "source": "./agentic/code/plugins/daemon",
  362. "description": "Persistent daemon session capabilities: Concierge front-end, session memory, scheduler integration",
  363. "version": "2026.11.8",
  364. "author": {
  365. "name": "AIWG Contributors"
  366. },
  367. "license": "MIT",
  368. "category": "productivity",
  369. "keywords": [
  370. "daemon",
  371. "persistent",
  372. "concierge",
  373. "session",
  374. "background",
  375. "interaction",
  376. "behavior"
  377. ]
  378. },
  379. {
  380. "name": "doc-intelligence",
  381. "source": "./agentic/code/plugins/doc-intelligence",
  382. "description": "Documentation intelligence addon for scraping, extraction, analysis, and generated-docs auditing.",
  383. "version": "2026.11.8",
  384. "author": {
  385. "name": "AIWG Contributors"
  386. },
  387. "license": "MIT",
  388. "category": "productivity",
  389. "keywords": [
  390. "documentation",
  391. "scraping",
  392. "pdf",
  393. "extraction",
  394. "llms-txt",
  395. "doc-analysis",
  396. "docs-audit",
  397. "discoverability"
  398. ]
  399. },
  400. {
  401. "name": "droid-bridge",
  402. "source": "./agentic/code/plugins/droid-bridge",
  403. "description": "MCP server bridging Claude Code to Factory Droid for batch operations and automated fixes",
  404. "version": "2026.11.8",
  405. "author": {
  406. "name": "AIWG Contributors"
  407. },
  408. "license": "MIT",
  409. "category": "productivity",
  410. "keywords": [
  411. "mcp",
  412. "factory-droid",
  413. "bridge",
  414. "automation",
  415. "batch-operations"
  416. ]
  417. },
  418. {
  419. "name": "guided-implementation",
  420. "source": "./agentic/code/plugins/guided-implementation",
  421. "description": "Bounded iteration control for autonomous issue-to-code implementation",
  422. "version": "2026.11.8",
  423. "author": {
  424. "name": "AIWG Contributors"
  425. },
  426. "license": "MIT",
  427. "category": "sdlc",
  428. "keywords": []
  429. },
  430. {
  431. "name": "line-memory",
  432. "source": "./agentic/code/plugins/line-memory",
  433. "description": "Bounded, plain-text project memory with least-recently-used retention.",
  434. "version": "2026.11.8",
  435. "author": {
  436. "name": "AIWG Contributors"
  437. },
  438. "license": "MIT",
  439. "category": "productivity",
  440. "keywords": [
  441. "memory",
  442. "recency",
  443. "retention",
  444. "plain-text",
  445. "project-context",
  446. "bounded-context"
  447. ]
  448. },
  449. {
  450. "name": "llm-wiki",
  451. "source": "./agentic/code/plugins/llm-wiki",
  452. "description": "LLM-maintained markdown wiki that compounds as sources are ingested. Thin topology declaration on the semantic memory kernel — ships schema profiles and page templates, no custom mechanics.",
  453. "version": "2026.11.8",
  454. "author": {
  455. "name": "AIWG Contributors"
  456. },
  457. "license": "MIT",
  458. "category": "productivity",
  459. "keywords": [
  460. "wiki",
  461. "llm-wiki",
  462. "knowledge-base",
  463. "markdown",
  464. "obsidian",
  465. "wikilink",
  466. "semantic-memory",
  467. "book-companion",
  468. "research",
  469. "personal-knowledge"
  470. ]
  471. },
  472. {
  473. "name": "nlp-prod",
  474. "source": "./agentic/code/plugins/nlp-prod",
  475. "description": "Tools, skills, and CLI extensions for designing and productionizing LLM inference pipelines. Pattern-guided, slim by default, eval-first.",
  476. "version": "2026.11.8",
  477. "author": {
  478. "name": "AIWG Contributors"
  479. },
  480. "license": "MIT",
  481. "category": "productivity",
  482. "keywords": [
  483. "llm",
  484. "inference",
  485. "pipeline",
  486. "production",
  487. "prompt-engineering",
  488. "eval",
  489. "rag",
  490. "state-machine",
  491. "chain",
  492. "agentic",
  493. "nlp",
  494. "cost-optimization"
  495. ]
  496. },
  497. {
  498. "name": "prose-integration",
  499. "source": "./agentic/code/plugins/prose-integration",
  500. "description": "Tools for reading, parsing, validating, and executing OpenProse programs from AIWG workflows",
  501. "version": "2026.11.8",
  502. "author": {
  503. "name": "AIWG Contributors"
  504. },
  505. "license": "MIT",
  506. "category": "productivity",
  507. "keywords": [
  508. "prose",
  509. "openprose",
  510. "contracts",
  511. "forme",
  512. "requires",
  513. "ensures",
  514. "markdown-programming"
  515. ]
  516. },
  517. {
  518. "name": "rlm",
  519. "source": "./agentic/code/plugins/rlm",
  520. "description": "RLM-inspired recursive context decomposition for processing arbitrarily large codebases and document corpora through programmatic sub-agent delegation",
  521. "version": "2026.11.8",
  522. "author": {
  523. "name": "AIWG Contributors"
  524. },
  525. "license": "MIT",
  526. "category": "productivity",
  527. "keywords": [
  528. "rlm",
  529. "recursive",
  530. "long-context",
  531. "decomposition",
  532. "sub-agent",
  533. "context-management",
  534. "chunking",
  535. "fan-out",
  536. "batch"
  537. ]
  538. },
  539. {
  540. "name": "semantic-memory",
  541. "source": "./agentic/code/plugins/semantic-memory",
  542. "description": "Topology-agnostic semantic memory operations: ingest, lint, query-capture, and structured event logging. Consumers declare a memory topology in their manifest.json; kernel skills read that contract to parameterize behavior.",
  543. "version": "2026.11.8",
  544. "author": {
  545. "name": "AIWG Contributors"
  546. },
  547. "license": "MIT",
  548. "category": "productivity",
  549. "keywords": [
  550. "semantic-memory",
  551. "kernel",
  552. "ingest",
  553. "lint",
  554. "query-capture",
  555. "log",
  556. "topology",
  557. "wiki",
  558. "knowledge-base"
  559. ]
  560. },
  561. {
  562. "name": "skill-factory",
  563. "source": "./agentic/code/plugins/skill-factory",
  564. "description": "Build, enhance, validate, and package Claude skills end-to-end. Coordinates skill-builder, skill-enhancer, quality-checker, and skill-packager via the skill-architect agent.",
  565. "version": "2026.11.8",
  566. "author": {
  567. "name": "AIWG Contributors"
  568. },
  569. "license": "MIT",
  570. "category": "productivity",
  571. "keywords": [
  572. "skill",
  573. "skills",
  574. "factory",
  575. "scaffolding",
  576. "validation",
  577. "packaging",
  578. "claude"
  579. ]
  580. },
  581. {
  582. "name": "star-prompt",
  583. "source": "./agentic/code/plugins/star-prompt",
  584. "description": "Tasteful prompt to encourage users to star the repository after successful command completion",
  585. "version": "2026.11.8",
  586. "author": {
  587. "name": "AIWG Contributors"
  588. },
  589. "license": "MIT",
  590. "category": "productivity",
  591. "keywords": [
  592. "engagement",
  593. "github",
  594. "stars",
  595. "feedback",
  596. "community"
  597. ]
  598. },
  599. {
  600. "name": "testing-quality",
  601. "source": "./agentic/code/plugins/testing-quality",
  602. "description": "Evidence-bound test conformance, platform protocols, normalization transactions and research-guided testing workflows",
  603. "version": "2026.11.8",
  604. "author": {
  605. "name": "AIWG Contributors"
  606. },
  607. "license": "MIT",
  608. "category": "sdlc",
  609. "keywords": []
  610. },
  611. {
  612. "name": "twelve-factor",
  613. "source": "./agentic/code/plugins/twelve-factor",
  614. "description": "Design-time and audit-time workflows for Twelve-Factor and modern 12+ Factor cloud-native application practices.",
  615. "version": "2026.11.8",
  616. "author": {
  617. "name": "AIWG Contributors"
  618. },
  619. "license": "MIT",
  620. "category": "productivity",
  621. "keywords": [
  622. "twelve-factor",
  623. "12-factor",
  624. "12+ factor",
  625. "cloud-native",
  626. "architecture",
  627. "audit",
  628. "observability",
  629. "supply-chain",
  630. "configuration",
  631. "runtime"
  632. ]
  633. },
  634. {
  635. "name": "uat-mcp",
  636. "source": "./agentic/code/plugins/uat-mcp",
  637. "description": "Agent-executable acceptance testing via MCP connections — generate, execute, and report on UAT plans that validate MCP tool surfaces.",
  638. "version": "2026.11.8",
  639. "author": {
  640. "name": "AIWG Contributors"
  641. },
  642. "license": "MIT",
  643. "category": "productivity",
  644. "keywords": [
  645. "uat",
  646. "mcp",
  647. "acceptance-testing",
  648. "testing",
  649. "quality-assurance",
  650. "mcp-tools",
  651. "agent-testing"
  652. ]
  653. },
  654. {
  655. "name": "verbalized-sampling",
  656. "source": "./agentic/code/plugins/verbalized-sampling",
  657. "description": "Training-free prompting technique that improves output diversity by 1.6-2.1x through verbalized probability distributions, addressing RLHF mode collapse",
  658. "version": "2026.11.8",
  659. "author": {
  660. "name": "AIWG Contributors"
  661. },
  662. "license": "MIT",
  663. "category": "productivity",
  664. "keywords": [
  665. "diversity",
  666. "verbalized-sampling",
  667. "mode-collapse",
  668. "creative",
  669. "ideation",
  670. "brainstorming",
  671. "synthetic-data",
  672. "prompting"
  673. ]
  674. },
  675. {
  676. "name": "training",
  677. "source": {
  678. "source": "github",
  679. "repo": "jmagly/aiwg-training",
  680. "ref": "main"
  681. },
  682. "description": "Corpus-to-dataset pipeline for AI training data curation. Ingests sources, synthesizes examples, generates DPO/KTO preference pairs, applies decontamination, and exports to Alpaca/ShareGPT/ChatML/JSONL/Parquet with provenance. Optional Python runtime (aiwg-training CLI) for scale.",
  683. "version": "1.0.0",
  684. "author": {
  685. "name": "AIWG Contributors"
  686. },
  687. "license": "MIT",
  688. "category": "development",
  689. "keywords": [
  690. "training-data",
  691. "fine-tuning",
  692. "dpo",
  693. "kto",
  694. "alpaca",
  695. "sharegpt",
  696. "decontamination",
  697. "synthetic-data",
  698. "datasheet"
  699. ]
  700. }
  701. ]
  702. }
README.md · README · 2,347 lines
  1. <div align="center">
  2. <a href="https://aiwg.io"><img src="docs/.public/aiwg-readme-hero-v2.png" alt="AIWG — multi-agent AI framework, one
  3. source of truth; network connecting AI tools" width="1000"></a>
  4. # AIWG
  5. **Reusable project context and specialist workflows for the AI tools you already use.**
  6. Plan software, coordinate specialist reviews, prepare campaigns, investigate incidents, organize research, curate
  7. media, and maintain operational knowledge. AIWG combines agents, skills, rules, templates, and workflow utilities
  8. around these tasks, adapting them to your existing AI provider.
  9. Project artifacts carry decisions from one session to the next. Domain frameworks supply the procedures; addons extend
  10. them with writing profiles, task loops, memory, testing tools, decision support, and other capabilities. The sections
  11. below show what you can do, how the pieces work together, and how to use them.
  12. The simplest setup is to paste this into a supported AI provider:
  13. ```text
  14. Install or repair AIWG for this project by following
  15. https://aiwg.io/setup.aiwg.yaml
  16. Explain the plan before changing anything, preserve my existing work, and ask
  17. me only for choices you cannot safely determine.
  18. ```
  19. The installer detects old, broken, duplicate, and development-mode installs,
  20. then guides you through repair or update. Once the CLI is healthy, guided
  21. setup records an interview plan, lets you review it, and applies the selected
  22. frameworks and integrations through the existing deployment owners. The apply
  23. report distinguishes core readiness from optional integration failures.
  24. For long-running agents that need an isolated executor, optionally install AIWG Cockpit with a self-hosted Agentic
  25. Sandbox executor you control and audit:
  26. ```text
  27. Install or repair AIWG Cockpit and Agentic Sandbox by following
  28. https://aiwg.io/agentic-sandbox/setup.aiwg.yaml
  29. Install the required prerequisites, explain the plan before changing anything,
  30. preserve my existing work, and ask me about the isolation, network, storage,
  31. and access choices you cannot safely determine.
  32. ```
  33. This option audits the host, installs the approved Docker or KVM/libvirt runtime
  34. and sandbox prerequisites, connects Cockpit to the real executor, applies your
  35. resource and access choices, and verifies the control and audit path end to end.
  36. If you prefer to install manually:
  37. ```bash
  38. npm i -g aiwg
  39. cd /path/to/your/project
  40. aiwg setup --scope project --providers <provider>
  41. aiwg setup --review
  42. aiwg setup --apply
  43. ```
  44. Replace `<provider>` with your AI tool's name, such as `claude`, `codex`,
  45. `copilot`, `cursor`, `omp`, or `pi`.
  46. The interview saves a plan without changing provider configuration. Review is
  47. read-only; apply asks for confirmation and reports the verified outcome. Optional
  48. Jev decision offload and direct workers require explicit opt-in. Repeating apply
  49. resumes unfinished actions and leaves completed actions alone. See the
  50. [guided setup reference](docs/getting-started/guided-setup.md) for headless flags,
  51. credential references, scope choices, and recovery. For a direct complete-system
  52. deployment, `aiwg use all --provider <provider>` remains available.
  53. For the complete beginner path and provider-name table, see
  54. [Install, Connect, and Verify](docs/getting-started/install-connect-verify.md).
  55. For a lightweight install that resolves signed, versioned resources from the release host, install the executable:
  56. ```bash
  57. npm i -g @aiwg/cli
  58. ```
  59. > Find the architecture-evolution workflow, read its requirements, and help me apply it to this project.
  60. See [Web-Backed AIWG Resources](docs/install/web-backed-resources.md) for source
  61. selection, exact-version overrides, cache verification, offline use, and the
  62. current framework-graph constraints.
  63. For a larger project, ask your AI assistant to establish project policy as well. The agent-led setup
  64. conversation should establish remotes, issue storage, delivery behavior,
  65. signing policy, and provider choices; the assistant discovers the project-setup workflow and handles its tools.
  66. macOS users: if npm fails with `EACCES` under `/usr/local/lib/node_modules`,
  67. use the [macOS Install Guide](docs/getting-started/macos-install.md).
  68. Agents and stewards setting up AIWG end-to-end should use the
  69. [Agentic Install Runbook](docs/agentic-install-runbook.md).
  70. [![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)
  71. [![npm downloads](https://img.shields.io/npm/dm/aiwg?color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
  72. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
  73. [![GitHub Stars](https://img.shields.io/github/stars/jmagly/aiwg?style=flat-square)](https://github.com/jmagly/aiwg/stargazers)
  74. [![Node Version](https://img.shields.io/badge/node-%E2%89%A524-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
  75. [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
  76. [![18 Providers](https://img.shields.io/badge/Providers-18-purple?style=flat-square)](#platform-support)
  77. [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/docs-aiwg-io)
  78. [![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io/badges)
  79. [**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)
  80. [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/BuAusFMxdA)
  81. [![Telegram](https://img.shields.io/badge/Telegram-Join-26A5E4?logo=telegram&logoColor=white&style=flat-square)](https://t.me/+oJg9w2lE6A5lOGFh)
  82. </div>
  83. ---
  84. ## Installation Troubleshooting
  85. ### Optional native features
  86. The base global install intentionally excludes native packages whose lifecycle
  87. scripts require explicit trust. Core deployment, discovery, and provider tooling
  88. work without them. Enable only the capability you need:
  89. > Enable the native features needed for interactive terminals, semantic search, or graph-backed artifacts in this
  90. > workspace. Explain which dependencies are required, install only the selected features, and verify they load.
  91. The feature installer writes a private manifest and lockfile under the AIWG user
  92. data directory and approves scripts only for that feature. Do not set a broad
  93. user-level npm `allow-scripts` policy. If an older install left native package
  94. files present but unbuilt, `aiwg doctor` reports the broken capability and the
  95. same scoped rebuild command.
  96. ### macOS npm `EACCES`
  97. If `npm install -g aiwg` fails with `EACCES` while writing to
  98. `/usr/local/lib/node_modules/aiwg`, npm is using a system-owned global install
  99. directory. The [Node.js setup guide](docs/getting-started/install-node.md) covers the supported runtime and
  100. version-manager choices. After setting up Node, run:
  101. ```bash
  102. npm install -g aiwg
  103. aiwg doctor
  104. ```
  105. If Node is already installed and you need a quick recovery, one manual alternative is a user-owned npm prefix. Choose
  106. this only after checking your existing Node version-manager configuration:
  107. ```bash
  108. npm config set prefix ~/.local
  109. echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
  110. echo 'source ~/.profile' >> ~/.zprofile
  111. source ~/.profile
  112. npm install -g aiwg
  113. ```
  114. See [macOS Install Guide](docs/getting-started/macos-install.md) for the full
  115. walkthrough. Avoid `sudo npm install -g aiwg` as the default fix; it can create
  116. root-owned npm files that break later upgrades.
  117. ### `aiwg` command not found
  118. If `aiwg` is not found after `npm i -g aiwg`, the npm global `bin` directory is not on your `PATH`. Confirm and fix:
  119. > Diagnose why this shell cannot find AIWG. Check the npm installation and PATH, and apply the appropriate local fix.
  120. You can also invoke AIWG without adjusting `PATH` by using `npx aiwg doctor`. For a broader health check — version,
  121. deployed providers, missing dependencies, kernel-skill probes — run `aiwg doctor`. See the [troubleshooting
  122. guide](docs/troubleshooting/index.md) for the full recovery paths.
  123. ---
  124. ## What AIWG Is
  125. AIWG gives your AI assistant reusable project context and specialist workflows. Its deployment layer connects those
  126. instructions to your provider: `aiwg use` copies markdown and YAML source files into the paths each provider reads, so
  127. one source of truth works across 19 named provider integrations. A twentieth `generic` adapter emits portable files
  128. for unrecognized or custom harnesses and is not counted as a named integration.
  129. Around that core, AIWG ships agent-facing utilities for work that benefits from additional structure: persistent
  130. artifact memory (`.aiwg/`), background orchestration, autonomous loops, artifact indexing, cost telemetry, health
  131. diagnostics, and more. These are tools the agent calls when the task calls for them — you stay in chat. Most are
  132. opt-in. The deployment layer works standalone as plain text files the platform reads natively.
  133. ### Project scope, user scope, and multi-project workspaces
  134. `aiwg use` supports project deployments, additive user mirrors, and a
  135. user-global bootstrap:
  136. - **Project scope** — default. Run `aiwg use all --provider <provider>` from a project root and the artifacts land in
  137. that provider's project paths. This keeps project-specific instructions associated with the intended repository.
  138. Some providers also use user-level surfaces; check the reported deployment scope. **This is the simplest start
  139. for a single project.**
  140. - **User scope (additive mirror)** — `aiwg use all --provider <provider> --scope user` keeps the
  141. project deployment and mirrors it to `~/.claude/agents/`,
  142. `~/.claude/skills/`, etc.
  143. - **Global bootstrap** — `aiwg use all --provider claude --global` installs
  144. framework and kernel assets in native user-level paths while leaving only
  145. lightweight context and provider bootstrap files in the current project.
  146. Ask the assistant to connect additional projects without
  147. deploying their own skill copies.
  148. Several repositories under one assistant or orchestrating session are supported. See
  149. [Working Across Multiple Projects](docs/guides/multi-project-workspaces.md) for setup, access, and sharing boundaries.
  150. Shared user-level instructions can be useful for personal conventions, while project-local instructions keep a team's
  151. requirements and decisions with its repository. Review both scopes when a provider uses them together. The installer
  152. and provider inventory describe where files will go, so you can distinguish instructions that follow you across
  153. projects from instructions intended for this workspace.
  154. See the [Agentic Install Runbook](docs/agentic-install-runbook.md) for the
  155. zero-to-running setup path, and the [CLI reference](docs/cli/reference.md) (under `aiwg use` →
  156. "Scope models") for the per-provider details and the global-install rough-edge
  157. inventory.
  158. ## Simple Building Blocks
  159. AIWG's workflow source is readable and editable. The main building blocks are:
  160. - **Agents** — specialist role instructions, such as Security Auditor or Test Architect, with defined responsibilities
  161. and supported tool access.
  162. - **Skills** — reusable procedures an agent can find from a goal and follow during a task.
  163. - **Commands** — explicit ways to request a workflow through the provider or CLI.
  164. - **Rules** — constraints for the assistant to follow, with tool-based checks where configured.
  165. - **Behaviors** — lifecycle actions and hooks on providers that support them.
  166. - **Templates** — structures for requirements, briefs, review reports, runbooks, and other outputs.
  167. Many assets use Markdown with YAML metadata; hooks and utilities may also include executable scripts or structured
  168. configuration. The provider determines how each asset is loaded or invoked. A role definition is not a separate model,
  169. and a written rule is not proof that its constraint was enforced.
  170. ## Why It Compounds
  171. The building blocks become more useful when workflows share their outputs:
  172. - A requirements analyst records acceptance criteria that the test engineer can later use to review coverage.
  173. - A security reviewer reads the same design decision as the implementation agent and records concerns against that decision.
  174. - A campaign brief gives content writers a shared audience, message, and review criteria.
  175. - A research note connects a source to the claim it supports, so a later synthesis can revisit the original evidence.
  176. - A runbook carries verification and recovery steps from planning into an operational change.
  177. Frameworks package these relationships: agents, skills, rules, and templates reference one another, while `.aiwg/`
  178. holds the project-specific work they produce. A review can follow **Primary Author → Reviewers → Synthesizer →
  179. Approval → Archive**, using parallel execution where the provider and task support it.
  180. For example, Monday's architecture review can become Thursday's implementation checklist. The second session needs to
  181. read the saved artifact and check that it is still applicable, but the team has a concrete record to work from rather
  182. than reconstructing the decision from conversation fragments.
  183. Research on structured artifacts, multi-agent review, and recovery informs this design. The [research
  184. foundations](#research-foundations) section preserves that background separately from claims about AIWG's own
  185. performance.
  186. ## How You Actually Use AIWG
  187. Describe the outcome you want in your AI tool. You do not need to learn a new command language or memorize skill
  188. names: “Help me start a project,” “Review this design for security risks,” or “Prepare a deployment plan with rollback.”
  189. The assistant interprets your intent, searches AIWG's capability graphs, reads the matching assets, and follows their
  190. procedures. Discovery brings together packaged AIWG capabilities and indexed project-local custom skills, agents,
  191. rules, and workflows; user-level assets participate when project policy allows them. Your team's indexed assets can
  192. therefore be found through the same conversation as AIWG's built-in capabilities. Newly authored assets need to be
  193. deployed or indexed before discovery can find them.
  194. For everyday setup and maintenance, ask:
  195. - “Set up the SDLC framework for this project and my AI tool.”
  196. - “Help me configure this project's tracker, delivery, signing, and provider preferences.”
  197. - “Create a new project for this idea.”
  198. - “Check which AIWG capabilities are active here and fix any setup problems.”
  199. - “Update AIWG and refresh this project's deployed assets.”
  200. The assistant handles discovery, artifact lookup, and the selected workflow's tools, then reports the result and its
  201. verification. Matching a capability is a starting point: the assistant still checks scope, prerequisites, and project
  202. policy before acting.
  203. For manual setup and maintenance, the usual commands are `aiwg use`, `aiwg init`, `aiwg refresh`, and `aiwg doctor`.
  204. The assistant handles other tooling. Advanced command syntax lives in the [CLI reference](docs/cli/reference.md).
  205. Deployment connects the supported workflow surface. Optional servers, storage services, and automation paths have
  206. their own prerequisites; installing assets does not mean all those services are running. You can start with one review
  207. or document task, then enable additional utilities as the work requires.
  208. ## What AIWG Is Not
  209. AIWG adds context, procedures, and support utilities around the AI tools you use. The deployment core writes
  210. provider-readable assets; optional orchestration and integration components can invoke provider runtimes or other
  211. configured services. The [architecture overview](docs/architecture-overview.md) distinguishes those components.
  212. It does not replace your provider subscription, your application's runtime, or the review needed before using
  213. generated work. Most workflows operate on project artifacts and source files rather than requiring your application to
  214. import an AIWG library. Keep generated configuration and project artifacts under the same review discipline as other
  215. repository changes.
  216. ## Who It's For
  217. AIWG is useful to individual developers, engineering teams, technical leaders, researchers, marketers, and operators
  218. whose work spans several tasks or sessions. It helps when you need reusable instructions, a shared record of
  219. decisions, or reviews from more than one perspective.
  220. You can start at several levels: a small documentation review, a focused code audit, a campaign brief, an
  221. investigation plan, or a complete development lifecycle. The [capability guide](docs/overview/capabilities.md) offers
  222. task-based routes, while this README keeps the broader feature and workflow detail available below.
  223. ---
  224. ## What Problems Does AIWG Solve?
  225. AI-assisted projects often need a deliberate way to carry context forward, recover from failed attempts, and make
  226. review criteria explicit. AIWG provides workflows and artifacts for each of those needs.
  227. ### 1. Maintaining Context Across Sessions
  228. Useful decisions can become scattered between conversations, issues, and source files. AIWG workflows save project
  229. outputs in `.aiwg/`, including requirements, architecture decisions, risk notes, test strategies, and campaign
  230. material.
  231. A later task can consult the relevant artifact and link its own work back to it. The requirements analyst writes a use
  232. case; the test engineer reads it to identify missing coverage; the implementation review checks whether the behavior
  233. matches the acceptance criteria. A changed decision can be recorded and propagated through those relationships.
  234. The structure also helps an agent select context for a large project. Instead of treating every file as equally
  235. relevant, a task can begin with a requirement, design record, or source note and follow its supporting references.
  236. Artifact lookup and indexing utilities help locate those records as the collection grows.
  237. The benefit depends on keeping artifacts current and actually consulting them. A saved file is a reusable source of
  238. context, not a guarantee that every later response will use it correctly.
  239. ### 2. Recovering from Failed Attempts
  240. A failing test or incomplete task needs a diagnosis, not just another attempt with the same assumptions. Agent loops
  241. support an execute-and-verify cycle that records failure information, adapts the next attempt, and stops at configured
  242. limits or escalation conditions.
  243. Use a loop for a bounded change with an observable completion criterion: fixing a regression, bringing a module under
  244. test, or carrying out a migration plan. External loop tooling adds process and session recovery where supported. Its
  245. usefulness depends on the provider, environment, task boundaries, and verification command; unattended execution is
  246. not a guarantee of completion.
  247. The record of attempts can help a later session understand what was tried and why it failed. That makes the recovery
  248. process reviewable even when the agent needs human input or cannot complete the task.
  249. ### 3. Making Quality Criteria Explicit
  250. Different reviews ask different questions. A security review examines exposure and trust boundaries; a performance
  251. review examines expected load and bottlenecks; a test review checks whether acceptance criteria are exercised; a
  252. writing review checks audience, clarity, and support for claims.
  253. AIWG supplies specialist roles and workflows that separate these concerns, combine their findings, and record open
  254. decisions. Phase gates can check whether the required artifacts and reviews are ready before the work advances.
  255. Project policy determines who must approve a decision and which checks are required.
  256. Multiple reviewers can still share an error. The practical benefit is a clearer review procedure and a saved account
  257. of the findings, with tests or other independent checks where available.
  258. ---
  259. ## The Six Core Components
  260. ### 1. Memory — Structured Semantic Memory
  261. The `.aiwg/` directory is a persistent artifact repository storing requirements, architecture decisions, test
  262. strategies, risk registers, and deployment plans across sessions. Artifacts provide retrievable project knowledge that
  263. can ground later work in recorded decisions and sources.
  264. Artifacts can be referenced with `@-mentions` (e.g., `@.aiwg/requirements/UC-001-login.md`). Context sharing between
  265. agents happens through artifacts: the requirements analyst writes use cases, the architecture designer reads them.
  266. ### 2. Reasoning — Multi-Agent Deliberation with Synthesis
  267. AIWG provides specialist role definitions organized by domain. A workflow can route a complex artifact through the
  268. reviewers the task requires:
  269. ```
  270. Architecture Document Creation:
  271. 1. Architecture Designer drafts SAD
  272. 2. Review Panel (3-5 agents run in parallel):
  273. - Security Auditor → threat perspective
  274. - Performance Engineer → scalability perspective
  275. - Test Architect → testability perspective
  276. - Technical Writer → clarity and consistency
  277. 3. Documentation Synthesizer merges all feedback
  278. 4. Human approval gate → accept, iterate, or escalate
  279. ```
  280. Each reviewer receives a defined responsibility and relevant context. The synthesis should resolve duplicate or
  281. conflicting findings, preserve uncertainty, and identify which conclusions were checked against sources or tests.
  282. Parallel reviews require the corresponding provider capability and available task budget. Small bounded judgments
  283. inside a workflow, such as a yes/no gate or a severity score, can go to [decision
  284. support](#decision-support--bounded-decisions-offloaded-to-jev) instead of a full reasoning pass.
  285. ### 3. Learning — Closed-Loop Self-Correction (Agent Loop)
  286. The agent loop executes tasks iteratively and uses verification results to guide the next attempt. Its task record can preserve
  287. failure analysis and revised strategies for subsequent iterations.
  288. ```
  289. Agent Loop Iteration:
  290. 1. Execute task with current strategy
  291. 2. Verify results (tests pass, lint clean, types check)
  292. 3. If failure: analyze root cause → extract structured learning → adapt strategy
  293. 4. Log iteration state (checkpoint for resume)
  294. 5. Repeat within configured limits; stop or escalate when required
  295. ```
  296. The external agent loop (`agent-loop-ext`) adds process tracking, session persistence, and recovery controls. For long-running work, define a time
  297. or iteration budget and inspect the provider-specific recovery behavior; surviving a particular failure depends on how
  298. the runner and host are configured.
  299. ### 4. Verification — Bidirectional Traceability
  300. AIWG supports links between documentation and code so reviewers can inspect relationships and find drift:
  301. ```typescript
  302. // src/auth/login.ts
  303. /**
  304. * @implements @.aiwg/requirements/UC-001-login.md
  305. * @architecture @.aiwg/architecture/SAD.md#section-4.2
  306. * @tests @test/unit/auth/login.test.ts
  307. */
  308. export function authenticateUser(credentials: Credentials): Promise<AuthResult> {
  309. ```
  310. Verification can follow Doc → Code, Code → Doc, Code → Tests, and Citations → Sources. These relationships make claims
  311. easier to inspect; they do not prove that implementation or citations are correct. Ask the workflow to report missing
  312. targets, inconsistent behavior, and unsupported source claims.
  313. ### 5. Planning — Phase Gates with Cognitive Load Management
  314. AIWG structures work using Cooper's Stage-Gate methodology (1990), breaking multi-month projects into bounded phases with explicit quality criteria and human approval:
  315. ```
  316. Inception → Elaboration → Construction → Transition → Production
  317. LOM ABM IOC PR
  318. ```
  319. Phase structure gives a team bounded decisions and review points: establish goals during Inception, evaluate design
  320. and risks during Elaboration, implement and verify during Construction, and prepare operational handoff during
  321. Transition. Templates help make the expected outputs visible. The project determines which artifacts, reviewers, and
  322. approval gates are appropriate; a small task need not use the full lifecycle.
  323. ### 6. Style — Controllable Voice Generation
  324. Voice profiles describe writing preferences such as formality, technical depth, directness, examples, uncertainty, and
  325. sentence variation. They give the assistant a reusable style specification that can be reviewed against the audience
  326. and document purpose.
  327. Built-in voices: `technical-authority` (docs, RFCs), `friendly-explainer` (tutorials), `executive-brief` (summaries),
  328. and `casual-conversational` (blogs, social). Ask “Create a reusable voice profile from these writing samples” to
  329. define your own.
  330. ---
  331. ## A Real Project Walkthrough
  332. The following illustrative customer-portal project shows how ordinary prompts connect the components across a
  333. lifecycle. These examples describe requests you can make, not a measured project outcome. The assistant discovers
  334. the relevant procedures and reads their instructions before carrying out each request.
  335. Start with a bounded goal, agree on acceptance criteria, and inspect the artifacts at each step. The time and review
  336. effort depend on the project, source quality, tools, and decisions involved. Smaller changes can enter at the phase
  337. that fits their current state rather than repeating the entire lifecycle.
  338. ### Inception
  339. > Help me define a customer portal with real-time chat. Walk me through the goals, users, constraints, and acceptance criteria.
  340. **Memory**: Intake forms capture goals, constraints, stakeholders in `.aiwg/intake/`
  341. **Planning**: Executive Orchestrator guides through structured questionnaire
  342. **Reasoning**: Requirements Analyst drafts initial use cases, Product Designer reviews UX
  343. **Verification**: Requirements reference intake forms, ensuring alignment
  344. **Human Gate**: Stakeholder reviews intake → approves transition to Elaboration
  345. ### Elaboration
  346. > Review the approved intake, develop the architecture and test strategy, and identify the risks we need to resolve.
  347. **Memory**: Architecture doc, ADRs, threat model, test strategy accumulate in `.aiwg/`
  348. **Reasoning**: Multi-agent review panel — Architecture Designer drafts, Security Auditor + Performance Engineer + Test Architect critique in parallel, Documentation Synthesizer merges
  349. **Learning**: The agent loop iterates on ADRs (generate options, evaluate against constraints, refine)
  350. **Style**: Technical documents use `technical-authority`, stakeholder summaries use `executive-brief`
  351. **Human Gate**: Architect reviews SAD, security team approves threat model
  352. ### Construction
  353. > Turn the reviewed design into an implementation plan. Implement authentication, verify its acceptance criteria,
  354. > and run the relevant tests.
  355. **Learning**: The agent loop handles implementation iterations — execute, verify (run tests), learn ("async race condition in token refresh"), adapt (add synchronization), retry
  356. **Verification**: Code references requirements (`@implements UC-001`), tests reference code
  357. **Memory**: Test plans, implementation, deployment scripts accumulate across iterations
  358. **Human Gate**: Code review approves merges, QA approves test results
  359. ### Transition
  360. > Prepare the production rollout with monitoring and rollback. After the required release approval, deploy it and
  361. > organize fourteen days of early-life support.
  362. **Planning**: Deployment checklist — monitoring, rollback plan, incident response
  363. **Learning**: Failed validation produces a diagnosis and a revised plan; retries follow the operation's recovery and
  364. approval requirements
  365. **Verification**: Deployment scripts reference architecture (which services, what order)
  366. **Human Gate**: Operations team reviews deployment plan → approves production release
  367. ---
  368. ## Claims, Evaluation, and Evidence
  369. Evaluate a workflow against the task it is meant to support. AIWG provides structures for review, traceability, and
  370. recovery; it does not promise a fixed cost saving, perfect citations, or error-free execution.
  371. | Capability to evaluate | Evidence to collect | Useful comparison |
  372. |------------------------|---------------------|-------------------|
  373. | Persistent project context | Whether a later session reads and applies a prior decision | The same kind of task with the team's usual handoff |
  374. | Specialist review | Correct findings, missed issues, and reviewer effort | A comparable review using the existing process |
  375. | Task recovery | Failure diagnosis, attempts, limits, and final verification | Similar failures handled without the loop |
  376. | Citation checking | Source existence and support for each material claim | Manual source inspection |
  377. | Structured planning | Completeness and usefulness of the resulting plan | The team's existing planning artifact |
  378. | Cost and throughput | Model calls, elapsed time, and human review effort | Comparable tasks with the same acceptance criteria |
  379. Research results from Agent Laboratory, self-consistency, tree search, and other systems inform the design. Their
  380. percentages and benchmark scores are not measurements of AIWG. The [research foundations](#research-foundations) and
  381. [reading list](docs/overview/reading-list.md) retain the underlying sources. The [executive
  382. brief](docs/overview/executive-brief.md) describes a practical pilot.
  383. ---
  384. ## When to Use AIWG (and When Not To)
  385. ### Good Fit
  386. 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.
  387. **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.
  388. ### Not the Best Fit
  389. A full lifecycle is usually unnecessary for a one-off question that needs no shared context, saved artifact, or
  390. follow-up. A focused writing, lookup, or review capability can still be useful without introducing every phase and
  391. gate.
  392. **Examples**: "Write a Python script to parse this CSV," "Fix this typo," "Explain how this code works."
  393. ### The Trade-off
  394. Match the workflow to the task. Use a bounded skill for a small result, a saved artifact when work needs to carry
  395. forward, and a phase-based process when coordination and review warrant it. Additional context, reviewers, or
  396. verification steps can add model calls and human effort; judge their value against the outcome you need.
  397. ```
  398. User intent → AIWG CLI → Deploy agents + rules + templates → AI platform
  399. │ │
  400. ▼ ▼
  401. "aiwg use all --provider X" Claude Code / Copilot /
  402. │ Cursor / Warp / Factory /
  403. ▼ OpenCode / Codex / Devin Desktop
  404. ┌──────────────┐
  405. │ Agents │ Specialized AI personas with domain expertise
  406. │ Commands │ CLI + slash commands for workflow automation
  407. │ Skills │ Natural language workflow triggers
  408. │ Rules │ Enforcement patterns (security, quality, anti-laziness)
  409. │ Templates │ SDLC artifact templates with progressive disclosure
  410. └──────────────┘
  411. │
  412. ▼
  413. .aiwg/ artifacts ← Persistent project memory across sessions
  414. ```
  415. ---
  416. ## How It Works
  417. > 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).
  418. **At a glance** — the deployment layer copies instructions into provider-readable locations, connects project context,
  419. and reports verification. The provider loads those instructions. Optional runtime components, such as artifact
  420. services or orchestration tools, perform additional work when configured and invoked.
  421. ```mermaid
  422. flowchart LR
  423. subgraph Source["AIWG framework source"]
  424. direction TB
  425. KERN["Kernel skills<br/>within provider listing budgets"]
  426. STD["Standard skills<br/>read from $AIWG_ROOT"]
  427. AGENT["Specialist agents"]
  428. RULES["Workflow rules"]
  429. TPL["Artifact templates"]
  430. end
  431. CLI(["aiwg use all<br/>--provider X"]) --> DEPLOY
  432. subgraph DEPLOY["Deploy step (one-shot)"]
  433. direction TB
  434. COPY["Copy kernel skills, agents,<br/>rules to provider-native dirs"]
  435. INDEX["Build artifact index<br/>~/.local/share/aiwg/index/"]
  436. CTX["Emit AIWG.md + AGENTS.md<br/>at project root"]
  437. end
  438. Source --> CLI
  439. DEPLOY --> Project
  440. subgraph Project["Your project (after deploy)"]
  441. direction TB
  442. PLAT[".claude/skills/<br/>.codex/agents/<br/>.warp/agents/ ..."]
  443. AIWGMD["AIWG.md / .hermes.md /<br/>WARP.md / AGENTS.md"]
  444. ART[".aiwg/<br/>requirements/<br/>architecture/<br/>..."]
  445. end
  446. Project --> SESS
  447. subgraph SESS["AI session (Claude / Codex / Hermes / etc.)"]
  448. direction TB
  449. NATIVE["Platform-native loader<br/>reads provider dir"]
  450. DISC(["Assistant capability discovery<br/>+ asset lookup"])
  451. end
  452. classDef optional stroke-dasharray: 5 5,fill:#fef9e7
  453. class DISC optional
  454. class INDEX optional
  455. ```
  456. **Multi-agent orchestration** — once deployed, AIWG coordinates specialized agents through phase-gated workflows:
  457. ```
  458. You: "transition to elaboration phase"
  459. AIWG: [Step 1] Requirements Analyst → Analyze vision document, generate use case briefs
  460. [Step 2] Architecture Designer → Baseline architecture, identify technical risks } parallel
  461. [Step 3] Security Architect → Threat model, security requirements }
  462. [Step 4] Documentation Synth. → Merge reviews into Architecture Baseline Milestone
  463. [Step 5] Human Gate → GO / CONDITIONAL_GO / NO_GO decision
  464. [Step 6] → Next phase or iterate
  465. ```
  466. 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.
  467. ---
  468. ## Features
  469. - **Specialist agents** — roles for architecture, implementation, testing, security, cloud, data engineering,
  470. research, content, and operations.
  471. - **Workflow skills and commands** — discoverable procedures for reviews, intake, research, curation, planning, and delivery.
  472. - **Rules and review criteria** — instructions for preserving work, handling sensitive configuration, checking claims,
  473. and reporting verification.
  474. - **Artifact templates** — structured requirements, design decisions, campaign briefs, source notes, runbooks, and
  475. review reports.
  476. - **Multi-provider deployment** — Google Antigravity CLI, Claude Code, OpenAI Codex, GitHub Copilot, Cursor, DeepSeek
  477. Harness, Factory AI, Flue (experimental), Grok Bot, Grok Build, Hermes, Muse Code, OpenCode, OpenClaw, OpenHuman, Pi Coding Agent, Oh My
  478. Pi, Warp Terminal, and Devin Desktop.
  479. - **Domain frameworks** — software development, forensics, marketing, research, media curation, operations, knowledge
  480. base, and security engineering.
  481. - **Dataset workflows** — assessment, indexing, lineage, synchronization, and retirement through dataset intelligence;
  482. the separate [`aiwg-training`](https://github.com/jmagly/aiwg-training) project covers training-data curation and
  483. exports.
  484. - **Memory addons** — compound memory, line memory, wiki-oriented knowledge, and artifact lookup for different
  485. persistence needs.
  486. - **Writing and voice tools** — reusable voice profiles, context-sensitive diagnostics, revision workflows, and
  487. alternatives for content generation.
  488. - **Testing quality** — test conformance, reversible normalization, mutation testing, and flaky-test review.
  489. See the [AIWG test conformance example](docs/conformance-aiwg-example.md) for reviewed source controls
  490. and runner evidence.
  491. - **Decision support** — optional offload of bounded decisions (yes/no gates, a pick from known options, severity
  492. scores) to Jev, with a typed answer, a confidence score, and a fallback to the assistant's own reasoning.
  493. - **Agent loops** — bounded execution, failure analysis, checkpoints, and supported process recovery.
  494. - **RLM** — recursive context decomposition for tasks whose source material needs to be divided into smaller working sets.
  495. - **YAML metalanguage** — structured workflow and artifact definitions with schema-oriented validation.
  496. - **MCP integration** — tools and resources exposed through configured servers and provider connections.
  497. - **Traceability and provenance** — relationships between requirements, code, tests, sources, and generated artifacts.
  498. - **Session history and diagnostics** — import, search, and inspect prior AI work across providers, check deployment
  499. health, and diagnose provider wiring.
  500. - **Project-local extensions and marketplace delivery** — keep custom instructions with the project and package
  501. reusable capabilities through the appropriate distribution path.
  502. The [framework and addon catalog](#what-you-get) below describes these capabilities in more detail. Compatibility and
  503. execution requirements are explicit in the [provider inventory](docs/providers/provider-inventory.md) and [CLI
  504. reference](docs/cli/reference.md).
  505. ---
  506. ## Quick Start
  507. > **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.
  508. > **Release verification:** Inspect the provenance and signature material for the release you install. The
  509. [verification guide](docs/releases/verifying.md) describes the available artifacts and commands.
  510. ### Install & Deploy
  511. The prompt-led installer at the top of this README is the canonical beginner path. For manual setup:
  512. ```bash
  513. npm i -g aiwg
  514. cd /path/to/your/project
  515. aiwg use all --provider claude # replace claude with your provider selector
  516. ```
  517. Deployment refreshes the shared context and reports verification and any required reload. Follow that result, then ask
  518. the agent to check the intended project and its AIWG connection. The [manual installation
  519. reference](docs/cli/install-and-repair.md) covers the terminal path in detail.
  520. For a deliberately narrower deployment, choose the relevant framework or addon instead of `all`. These are
  521. alternatives, not a sequence of required setup steps:
  522. ```bash
  523. aiwg use sdlc --provider claude # Software development
  524. aiwg use forensics --provider claude # Investigation workflows
  525. aiwg use marketing --provider claude # Campaign and content work
  526. aiwg use media-curator --provider claude # Media collections
  527. aiwg use research --provider claude # Research artifacts
  528. aiwg use civic-action --provider claude # Civic review and preparation
  529. aiwg use rlm --provider claude # Context decomposition
  530. ```
  531. For maintenance or an existing workspace that needs context migration, preview the relevant regeneration branch rather
  532. than treating every branch as installation:
  533. > Preview how to refresh this workspace’s provider context. If it needs existing-project extraction or migration,
  534. > explain the proposed changes, preserve project-specific instructions, and verify the result.
  535. The [regeneration guide](docs/regenerate-guide.md) also covers canonical refresh and legacy compatibility. Use the
  536. branch that matches the workspace state. To scaffold a new project rather than connect the current one, see the
  537. [new-project guide](docs/getting-started/new-project.md).
  538. ### Get a First Useful Result
  539. After setup, ask your agent:
  540. ```text
  541. Use AIWG to review this project's README for unclear positioning and missing
  542. onboarding steps. Save a report at
  543. .aiwg/marketing/brand/audit/readme-review.md with file references and the
  544. three highest-priority fixes. Leave the README unchanged.
  545. ```
  546. Open the report and check the source references, reader impact, and proposed fixes. In a later session, ask the agent
  547. to read that report and implement the first agreed change. The [first-result
  548. walkthrough](docs/getting-started/just-try-it.md) includes an illustrative finding and alternative tasks. Setup
  549. readiness is the prerequisite; a useful artifact is what lets you assess the workflow.
  550. ### Customize Without Forking
  551. Author project-specific rules, skills, agents, addons, or frameworks
  552. directly under `.aiwg/{extensions,addons,frameworks}/<name>/`. Use
  553. `.aiwg/plugins/<name>/` only when you are wrapping a bundle for marketplace
  554. delivery. No fork, no rebuild. Discovered automatically by `aiwg use`.
  555. > Create a project-local extension named my-team-rules with a starter rule. Deploy it here, check its health, and
  556. > help me prepare it for upstream promotion once it is proven.
  557. The bundle is **byte-identical** in shape to its upstream form, so
  558. promotion uses a hash-verified copy with zero rewrite. See the
  559. [customization guide](docs/customization/README.md) for the three paths
  560. (project-local, fork, corpus).
  561. ### Claude Code Marketplace (Alternative)
  562. > Add the AIWG marketplace to Claude Code and install the SDLC, Agent Loop, and Compound Memory plugins.
  563. The marketplace contains independently packaged framework and addon
  564. plugins, so you can install only the capabilities a Claude Code workspace
  565. needs. Source-distributed opt-in addons such as Civic Action deploy with
  566. `aiwg use civic-action` and do not imply a marketplace wrapper.
  567. ### Multi-Platform Deployment
  568. ```bash
  569. aiwg use all --provider antigravity # Google Antigravity CLI (alias: agy)
  570. aiwg use all --provider claude # Claude Code
  571. aiwg use all --provider codex # OpenAI Codex
  572. aiwg use all --provider copilot # GitHub Copilot
  573. aiwg use all --provider cursor # Cursor
  574. aiwg use all --provider dsh # DeepSeek Harness
  575. aiwg use all --provider factory # Factory AI
  576. aiwg use all --provider grokbot # Grok Bot
  577. aiwg use all --provider grok-build # Grok Build
  578. aiwg use all --provider opencode # OpenCode
  579. aiwg use all --provider warp # Warp Terminal
  580. aiwg use all --provider devin # Devin Desktop
  581. aiwg use all --provider openclaw # OpenClaw
  582. aiwg use all --provider hermes # Hermes
  583. aiwg use all --provider openhuman # OpenHuman
  584. aiwg use all --provider pi # Pi Coding Agent
  585. aiwg use all --provider omp # Oh My Pi
  586. aiwg use all --provider muse # Muse Code
  587. ```
  588. `all` means the complete deployable end-user surface. It intentionally omits
  589. contributor-only development bundles and packages that cannot be deployed
  590. directly.
  591. ### First-Party Integrators
  592. AIWG can also be distributed through another runtime. Check the integrator's version and included assets before
  593. assuming that its bundled surface matches a standalone AIWG install. Follow that runtime's setup instructions, then
  594. verify the project connection.
  595. | Partner | Install | What you get |
  596. |---------|---------|--------------|
  597. | **[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. |
  598. If you ship a product that bundles AIWG and want to be listed here, open an issue at https://github.com/jmagly/aiwg/issues.
  599. ---
  600. ## What You Get
  601. AIWG installs reusable context, specialist agents, workflow skills, rules, and
  602. artifact templates into the AI tools your team already uses. This fragment keeps
  603. the older README's broad inventory shape while updating claims against the
  604. current repository. Counts shown in framework rows are source-file counts from
  605. this working tree; addon rows omit totals because several addons expose
  606. capabilities through manifests, docs, scripts, or nested skill packages.
  607. ### Frameworks
  608. | Framework | Source Snapshot | What It Helps You Do |
  609. |-----------|-----------------|----------------------|
  610. | **[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 |
  611. | **[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 |
  612. | **[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 |
  613. | **[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 |
  614. | **[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 |
  615. | **[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 |
  616. | **[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 |
  617. | **[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 |
  618. | **[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 |
  619. Start with [Install, Connect, and Verify](docs/getting-started/install-connect-verify.md),
  620. then deploy a framework with `aiwg use <framework>`. The [capability reference](docs/cli/reference.md)
  621. lists the current framework names accepted by the CLI.
  622. ### Addons
  623. | Addon | What It Helps You Do |
  624. |-------|----------------------|
  625. | **[AIWG Utils](agentic/code/addons/aiwg-utils/)** | Shared rules, discovery helpers, regeneration support, mention tooling, workspace maintenance, and stewardship primitives used across AIWG |
  626. | **[Agent Loop](agentic/code/addons/agent-loop/)** | Run bounded iterative agent loops with recovery, reflection, completion tracking, and resumable progress tracking |
  627. | **[RLM](agentic/code/addons/rlm/)** | Decompose large codebases or document corpora into smaller reviewed slices through recursive planning and subtask execution |
  628. | **[Composition Engine](agentic/code/addons/composition-engine/)** | Define and validate provider-neutral Flow graph contracts for composed workflows |
  629. | **[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` |
  630. | **[Graph Pattern](agentic/code/addons/graph-pattern/)** | Add an optional graph-oriented profile over AIWG Flow for conditional routes, reducers, and graph validation |
  631. | **[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 |
  632. | **[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 |
  633. | **[Daemon](agentic/code/addons/daemon/)** | Run opt-in persistent session support for background tasks, queues, health checks, and scheduler integration |
  634. | **[Agentic Installer](agentic/code/addons/agentic-installer/)** | Use `setup.aiwg.io/v1` SetupManifest files for reproducible, agent-driven install workflows with recovery paths |
  635. | **[AIWG Dev](agentic/code/addons/aiwg-dev/)** | Scaffold and validate AIWG source packages, skills, agents, commands, and rules; install explicitly for contributor work |
  636. | **[Skill Factory](agentic/code/addons/skill-factory/)** | Build, enhance, validate, and package skills through a dedicated skill-authoring workflow |
  637. | **[AIWG Evals](agentic/code/addons/aiwg-evals/)** | Run agent and workflow evaluation patterns with explicit benchmark inputs and quality scoring |
  638. | **[Monitorability Red Team](agentic/code/addons/monitorability-red-team/)** | Exercise synthetic local fixtures that expose multi-agent monitoring limits and evidence blind spots |
  639. | **[Long-Context Bench](agentic/code/addons/long-context-bench/)** | Benchmark compressed skim plus exact recovery against current context baselines |
  640. | **[Natural-Language Harness](agentic/code/addons/natural-language-harness/)** | Map inspectable natural-language policy documents to deterministic AIWG mechanisms and ablation reports |
  641. | **[Premortem v2](agentic/code/addons/premortem-v2/)** | Generate, select, and independently verify bounded risk sets before execution |
  642. | **[Century Readiness](agentic/code/addons/century-readiness/)** | Review long-horizon stewardship, degradation, replacement, evidence, and meaning-preservation risks |
  643. | **[Dataset Intelligence](agentic/code/addons/dataset-intelligence/)** | Route dataset intake, planning, materialization, traceability, verification, export, synchronization, and retirement through governed workflows |
  644. | **[Schema Governance](agentic/code/addons/schema-governance/)** | Discover, author, validate, evolve, and normalize schemas across datasets and SDLC artifacts |
  645. | **[Compound Memory](agentic/code/addons/compound-memory/)** | Govern promotion from raw evidence and session candidates into line memory or linked wiki knowledge with lineage |
  646. | **[Line Memory](agentic/code/addons/line-memory/)** | Keep a bounded plain-text set of durable project facts with recency retention and reviewed lifecycle operations |
  647. | **[LLM Wiki](agentic/code/addons/llm-wiki/)** | Maintain a Markdown wiki topology for entities, concepts, sources, comparisons, and syntheses |
  648. | **[Semantic Memory](agentic/code/addons/semantic-memory/)** | Provide topology-agnostic memory operations for ingest, lint, query/capture, and event logging |
  649. | **[Auto Memory](agentic/code/addons/auto-memory/)** | Seed Claude Code Automatic Memory files with AIWG-aware testing, debugging, and architecture sections |
  650. | **[Agent Persistence](agentic/code/addons/agent-persistence/)** | Supply reusable human-in-the-loop gate definitions for destructive actions, overrides, and recovery escalation |
  651. | **[AIWG Hooks](agentic/code/addons/aiwg-hooks/)** | Provide hook templates for workflow tracing, permissions, session management, context injection, and quality gates |
  652. | **[AIWG Fleet](agentic/code/addons/aiwg-fleet/)** | Apply quiet-bot, mention-only participation, and small-plan cost-discipline policies across multi-project fleets |
  653. | **[Browser Control](agentic/code/addons/browser-control/)** | Drive a user-authorized Chromium-derived browser through Playwright MCP with allow-list and audit boundaries |
  654. | **[Droid Bridge](agentic/code/addons/droid-bridge/)** | Bridge Claude Code to Factory Droid for batch operations and automated fixes through MCP |
  655. | **[MCP/UAT Toolkit](agentic/code/addons/uat-mcp/)** | Generate, execute, and report user-acceptance tests against MCP tool surfaces |
  656. | **[Civic Action](agentic/code/addons/civic-action/)** | Prepare evidence-bound civic research, public-records planning, meeting review, local-resource profiles, corrections, and publication review |
  657. | **[Network Analysis](agentic/code/addons/network-analysis/)** | Governed saved-PCAP/PCAPNG analysis with bounded TShark recipes, cited packet evidence, and optional local Termshark review |
  658. | **[Testing Quality](agentic/code/addons/testing-quality/)** | Assess test conformance, normalize suites with reversible plans, and add TDD, mutation, flaky-test, and factory workflows |
  659. | **[Writing Quality](agentic/code/addons/writing-quality/)** | Review editorial quality, author requirements, and voice consistency without treating heuristic scores as authorship proof |
  660. | **[Voice Framework](agentic/code/addons/voice-framework/)** | Define, analyze, blend, and apply reusable writing voice profiles and runtime-selectable output modes |
  661. | **[Color Palette](agentic/code/addons/color-palette/)** | Generate and review accessible color palettes using color theory, trend research, and WCAG checks |
  662. | **[Doc Intelligence](agentic/code/addons/doc-intelligence/)** | Scrape, extract, split, audit, and synchronize documentation sources |
  663. | **[Prose Integration](agentic/code/addons/prose-integration/)** | Detect, read, validate, wire, and run OpenProse contract programs in supported AIWG sessions |
  664. | **[NLP Prod](agentic/code/addons/nlp-prod/)** | Design and productionize LLM inference pipelines with eval-first, pattern-guided workflow support |
  665. | **[Context Curator](agentic/code/addons/context-curator/)** | Filter distractors and curate context packs for agent work where irrelevant material can derail results |
  666. | **[Twelve-Factor](agentic/code/addons/twelve-factor/)** | Review or design applications against Twelve-Factor and modern cloud-native criteria |
  667. | **[Verbalized Sampling](agentic/code/addons/verbalized-sampling/)** | Apply and evaluate verbalized probability-distribution prompting for output diversity experiments |
  668. | **[Star Prompt](agentic/code/addons/star-prompt/)** | Offer a tasteful repository-star prompt after successful command completion |
  669. Addon details live in each source directory and, where public docs exist, under
  670. `docs/addons/`. Use [Key Addons](docs/getting-started/key-addons.md) for a
  671. guided end-user selection path.
  672. ---
  673. ### Agents
  674. Specialized AI personas deploy to your platform with defined responsibilities,
  675. tools, and operating rhythms. The exact inventory changes as frameworks evolve,
  676. so this README keeps durable groupings and examples instead of relying on one
  677. global total.
  678. #### SDLC Agents
  679. | Domain | Examples |
  680. |--------|----------|
  681. | **Testing & Quality** | Test Engineer, Test Architect, Mutation Analyst, Regression Analyst, Reliability Engineer |
  682. | **Security & Compliance** | Security Auditor, Security Architect, Compliance Checker, Privacy Officer, Citation Verifier |
  683. | **Architecture & Design** | Architecture Designer, API Designer, Cloud Architect, System Analyst, Product Designer, Decision Matrix Expert |
  684. | **DevOps & Cloud** | AWS Specialist, Azure Specialist, GCP Specialist, Kubernetes Expert, DevOps Engineer, Multi-Cloud Strategist |
  685. | **Backend & Data** | Django Expert, Spring Boot Expert, Data Engineer, Database Optimizer, Software Implementer, Incident Responder |
  686. | **Frontend & Mobile** | React Expert, Frontend Specialist, Mobile Developer, Accessibility Specialist, UX Lead |
  687. | **AI/ML & Performance** | AI/ML Engineer, Performance Engineer, Cost Optimizer, Metrics Analyst |
  688. | **Code Quality** | Code Reviewer, Debugger, Dead Code Analyzer, Technical Debt Analyst, Legacy Modernizer |
  689. | **Documentation** | Technical Writer, Documentation Synthesizer, Documentation Archivist, Context Librarian |
  690. | **Requirements & Planning** | Requirements Analyst, Requirements Reviewer, Intake Coordinator, RACI Expert |
  691. | **Agent/Tool Smiths** | AgentSmith, CommandSmith, MCPSmith, SkillSmith, ToolSmith |
  692. | **Governance & Meta** | Executive Orchestrator, Recovery Orchestrator, Migration Planner |
  693. #### Forensics Agents
  694. | Agent | What It Does |
  695. |-------|-------------|
  696. | Forensics Orchestrator | Coordinates investigation scope, evidence handling, analysis, and reporting |
  697. | Triage Agent | Captures volatile data following evidence-priority guidance |
  698. | Acquisition Agent | Collects evidence with chain-of-custody and hash verification |
  699. | Log Analyst | Reviews auth, syslog, journal, and application logs for suspicious activity |
  700. | Persistence Hunter | Checks cron, systemd, SSH keys, LD_PRELOAD, PAM modules, and kernel-module indicators |
  701. | Container Analyst | Reviews Docker, containerd, and Kubernetes evidence |
  702. | Network Analyst | Reviews connection state, DNS, beaconing, and exfiltration indicators |
  703. | Memory Analyst | Supports Volatility-style memory forensics workflows |
  704. | Cloud Analyst | Reviews AWS, Azure, and GCP audit trails and IAM posture |
  705. | Timeline Builder | Correlates events into chronological incident timelines |
  706. | IOC Analyst | Extracts and formats indicators for downstream response |
  707. | Recon Agent | Builds a target baseline for authorized investigation |
  708. | Reporting Agent | Produces structured executive and technical investigation reports |
  709. #### Marketing Agents
  710. | Domain | Examples |
  711. |--------|----------|
  712. | **Strategy** | Campaign Strategist, Brand Guardian, Positioning Specialist, Market Researcher, Content Strategist, Channel Strategist |
  713. | **Creation** | Copywriter, Content Writer, Email Marketer, Social Media Specialist, SEO Specialist, Graphic Designer, Art Director |
  714. | **Management** | Campaign Orchestrator, Production Coordinator, Traffic Manager, Asset Manager, Workflow Coordinator |
  715. | **Analytics** | Marketing Analyst, Data Analyst, Attribution Specialist, Reporting Specialist, Budget Planner |
  716. | **Communications** | PR Specialist, Crisis Communications, Corporate Communications, Internal Communications, Media Relations |
  717. #### Other Framework Agents
  718. Research uses discovery, acquisition, documentation, citation, quality,
  719. archival, provenance, and workflow roles. Media Curator uses discography/source,
  720. acquisition, quality, metadata, and completeness roles. Ops Complete adds
  721. runbook execution and inventory roles. Security Engineering adds security
  722. specialists for applied security decisions and supply-chain review.
  723. ---
  724. ### Rules
  725. Rules are durable guardrails that deploy with the frameworks or addons that own
  726. them. They prevent common agent failure modes and define review boundaries.
  727. #### Core Rules
  728. | Rule | Severity | What It Enforces |
  729. |------|----------|-----------------|
  730. | `no-attribution` | CRITICAL | AI tools are tools; do not add AI attribution to commits, PRs, docs, or code |
  731. | `token-security` | CRITICAL | Keep tokens and secrets out of source; use scoped lifetime and restricted file permissions |
  732. | `versioning` | CRITICAL | Use the repository's CalVer release format consistently |
  733. | `citation-policy` | CRITICAL | Do not fabricate citations, DOIs, URLs, or research claims |
  734. | `anti-laziness` | HIGH | Do not delete tests, skip required checks, remove features, or weaken assertions to pass |
  735. | `executable-feedback` | HIGH | Run appropriate validation before returning implementation work |
  736. | `failure-mitigation` | HIGH | Detect and recover from hallucination, context loss, instruction drift, safety, technical, and consistency failures |
  737. | `research-before-decision` | HIGH | Inspect the codebase and docs before making technical decisions |
  738. | `instruction-comprehension` | HIGH | Parse prohibitions, requirements, and preferences before acting |
  739. | `subagent-scoping` | HIGH | Keep delegated tasks focused and bounded when delegation is used |
  740. #### Domain Rules
  741. | Domain | Examples |
  742. |--------|----------|
  743. | **SDLC** | HITL gates, provenance tracking, artifact discovery, phase gates, reproducibility validation, agent-friendly code, fallback, review, and handoff rules |
  744. | **Forensics** | Evidence integrity, chain of custody, forensic reporting, and authorized investigation boundaries |
  745. | **Security Engineering** | Cryptographic decision boundaries, runtime secret hygiene, supply-chain trust, physical-access threat modeling, and DFIR readiness handoff |
  746. | **Ops** | Ops safety, executable runbook format, evidence governance, issue tracking, and cross-repo reference rules |
  747. | **Civic Action** | Human authority, citation, publication, public-source, privacy, and anti-targeting boundaries |
  748. | **Addon Rules** | Browser authorization, dataset boundaries, agentic installer safety, voice/output behavior, and hook discipline |
  749. ---
  750. ### Skills
  751. Skills are natural-language workflows. A user describes an outcome, the agent
  752. discovers the relevant skill, loads its instructions, and applies its protocol.
  753. The current repo contains a large and changing skill surface, so this section
  754. keeps durable categories and examples.
  755. | Category | Examples |
  756. |----------|---------|
  757. | **Capability discovery and setup** | `aiwg-utils-quickref`, `steward`, `aiwg-status`, `aiwg-doctor`, `use`, provider regeneration |
  758. | **SDLC and delivery** | `intake-wizard`, `sdlc-accelerate`, gate evaluation, delivery-track flows, deployment, guided implementation |
  759. | **Testing and quality** | `test-conformance`, `test-normalize`, `test-platform-research`, TDD, mutation, flaky-test review, factory generation |
  760. | **Security and forensics** | supply-chain hardening, auth-factor design, degraded-mode review, DFIR readiness, log analysis, IOC extraction |
  761. | **Research and knowledge** | source acquisition, paper induction, GRADE checks, citation work, wiki ingest, synthesis, knowledge-base health |
  762. | **Marketing and content** | campaign intake, creative brief, brand compliance, social strategy, email campaigns, performance digests |
  763. | **Media curation** | source discovery, acquisition planning, transcript sidecars, metadata tagging, quality filtering, archive verification |
  764. | **Datasets and schemas** | dataset intake, source assessment, capability recommendation, plan review, ingest, trace, verify, export, retire |
  765. | **Memory and persistence** | line-memory operations, compound-memory review, semantic-memory capture/query, llm-wiki topology |
  766. | **Operations and automation** | runbook execution, ops verification, activity logs, hooks, daemon sessions, schedule support |
  767. | **Authoring and development** | skill creation, addon/framework scaffolding, validation, schema governance, doc synchronization |
  768. ---
  769. ## Framework Deep Dives
  770. ### SDLC Complete — Full Software Development Lifecycle
  771. The SDLC framework implements a phase-gated development lifecycle with
  772. specialized agents, enforcement rules, and artifact templates. Natural-language
  773. requests drive phase transitions with reviewable quality gates.
  774. ```text
  775. ┌──────────┐ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ ┌────────────┐
  776. │ CONCEPT │───▶│ INCEPTION │───▶│ ELABORATION │───▶│CONSTRUCTION│───▶│ TRANSITION │
  777. │ │ │ │ │ │ │ │ │ │
  778. │ Intake │ │ Vision │ │ Architecture │ │ Code │ │ Deploy │
  779. │ Wizard │ │ Requirements│ │ Risk Retire │ │ Test │ │ Hypercare │
  780. │ Solution │ │ Stakeholder │ │ Prototype │ │ Review │ │ Handoff │
  781. │ Profile │ │ Analysis │ │ API Design │ │ Iterate │ │ Knowledge │
  782. └──────────┘ └──────┬──────┘ └──────┬───────┘ └─────┬──────┘ └────────────┘
  783. │ │ │
  784. ┌──▼──┐ ┌──▼──┐ ┌──▼──┐
  785. │ LOM │ │ ABM │ │ IOC │
  786. │Gate │ │Gate │ │Gate │
  787. └─────┘ └─────┘ └─────┘
  788. LOM = Lifecycle Objectives Milestone ABM = Architecture Baseline Milestone
  789. IOC = Initial Operational Capability
  790. ```
  791. **Example SDLC prompts:**
  792. | Ask your assistant | Phase | What It Does |
  793. |---------|-------|-------------|
  794. | “Help me define the goals and constraints for this project.” | Concept | Generate project intake from a natural-language description |
  795. | “Validate our intake and assign the initial work.” | Concept -> Inception | Validate intake and begin agent assignments |
  796. | “Understand this codebase and draft its project intake.” | Concept | Scan an existing codebase and generate intake from analysis |
  797. | “Turn this concept into an agreed project vision.” | Concept -> Inception | Transition with intake validation and vision alignment |
  798. | “Review our architecture and resolve the major risks.” | Inception -> Elaboration | Baseline architecture and retire major risks |
  799. | “Plan the implementation from our reviewed design.” | Elaboration -> Construction | Prepare iteration planning, scale delivery, and begin implementation |
  800. | “Check whether this implementation is ready for release.” | Construction -> Transition | Validate IOC, deployment readiness, and operational handoff |
  801. | “Validate the requirements for the next delivery batch.” | Any | Prepare validated requirements ahead of delivery |
  802. | “Implement this batch with tests and quality checks.” | Any | Run test-driven delivery with quality gates |
  803. | “Coordinate requirements discovery with the next delivery iteration.” | Any | Coordinate discovery and delivery tracks |
  804. | “Prepare this release for production, including rollback.” | Transition | Select deployment strategy, validate, and prepare rollback/regression checks |
  805. | “Help us triage this incident and plan recovery.” | Operations | Triage, resolve, and review incidents |
  806. | “Review security risks and track the required fixes.” | Any | Run continuous security validation and threat review |
  807. | “Find the performance bottlenecks and verify improvements.” | Any | Baseline, identify bottlenecks, optimize, and validate SLOs |
  808. | “Review what we learned and track improvements.” | Any | Capture feedback and track improvement actions |
  809. | “Assess this change and coordinate its review.” | Any | Assess impact, coordinate review, and manage communication |
  810. | “Identify and track the risks to this project.” | Any | Identify, assess, track, and retire risks |
  811. | “Map our requirements to evidence and identify gaps.” | Any | Map requirements, collect evidence, and identify gaps |
  812. | “Prepare the documentation and operational handover.” | Transition | Prepare documentation, shadowing, validation, and handover |
  813. | “Create an onboarding plan for our new teammate.” | Any | Structure onboarding, training, buddy support, and follow-up |
  814. | “Organize early-life support for this release.” | Transition | Track early-life support, SLOs, and rapid-response items |
  815. | “Review the evidence for our next phase gate.” | Any | Run multi-agent phase-gate validation |
  816. | “Check that the next team has a complete handoff.” | Any | Validate handoff between phases and tracks |
  817. | “Work through these issues with bounded retries and verification.” | Construction | Run bounded issue-to-code iteration with validation and escalation |
  818. **SDLC Accelerate — from idea to reviewed planning artifacts:**
  819. > Turn an AI-powered code review tool with GitHub integration into reviewed intake, architecture, risks, and a
  820. > delivery plan. Use the existing codebase if present, and resume saved planning work instead of starting over.
  821. It can generate intake, vision, use cases, architecture baseline, risk register,
  822. test strategy, and deployment planning artifacts with human review between
  823. major phases.
  824. **Dual-Track Iteration Model:**
  825. ```text
  826. ┌─────────────────────────────────────────────────┐
  827. │ ITERATION N │
  828. │ │
  829. │ Discovery Track Delivery Track │
  830. │ (Next iteration) (Current iteration) │
  831. │ │
  832. │ ┌─────────────┐ ┌──────────────┐ │
  833. │ │ Requirements│ │ Implement │ │
  834. │ │ Research │ │ Test │ │
  835. │ │ Design │ │ Review │ │
  836. │ │ Validate │ │ Deploy │ │
  837. │ └─────┬───────┘ └──────┬───────┘ │
  838. │ │ │ │
  839. │ └────────────┬────────────┘ │
  840. │ │ │
  841. │ ┌──────▼──────┐ │
  842. │ │ Iteration │ │
  843. │ │ Assessment │ │
  844. │ └─────────────┘ │
  845. └─────────────────────────────────────────────────┘
  846. ```
  847. **Metrics and Quality Tracking:**
  848. | Metric Category | Metrics Tracked |
  849. |-----------------|-----------------|
  850. | **DORA** | Deployment frequency, lead time, change failure rate, MTTR |
  851. | **Velocity** | Story points, cycle time, throughput |
  852. | **Flow** | WIP limits, flow efficiency, blocked items |
  853. | **Quality** | Test coverage, defect metrics, code quality, technical debt |
  854. | **Operational** | SLO/SLI, infrastructure, incidents, cost |
  855. ### Forensics Complete — Digital Forensics and Incident Response
  856. Forensics Complete supports authorized DFIR work following NIST SP 800-86-style
  857. evidence handling, MITRE ATT&CK mapping, Sigma hunting, timeline construction,
  858. and structured reporting.
  859. ```text
  860. ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐
  861. │ SCOPE │───▶│ TRIAGE │───▶│ ACQUIRE │───▶│ ANALYZE │───▶│ REPORT │
  862. │ │ │ │ │ │ │ │ │ │
  863. │ Profile │ │ Volatile │ │ Evidence │ │ Log │ │ Executive│
  864. │ target │ │ data │ │ collection │ │ Timeline │ │ summary │
  865. │ system │ │ capture │ │ Chain of │ │ IOC │ │ Findings │
  866. │ │ │ RFC 3227 │ │ custody │ │ Sigma │ │ Timeline │
  867. └──────────┘ └──────────┘ └────────────┘ └──────────┘ └──────────┘
  868. │
  869. SHA-256 hash
  870. verification
  871. ```
  872. **Example investigation prompts:**
  873. >
  874. > Profile the affected system, triage the incident, and plan evidence acquisition with chain-of-custody records.
  875. >
  876. > Investigate the collected evidence, build a timeline, and look for related indicators of compromise.
  877. >
  878. > Summarize the findings, unresolved questions, and current investigation status.
  879. **Supported Evidence Sources:**
  880. | Source | Agent | Analysis |
  881. |--------|-------|----------|
  882. | Auth logs | Log Analyst | Brute force, privilege escalation, lateral movement |
  883. | Syslog / journal | Log Analyst | System events, service anomalies |
  884. | Network connections | Network Analyst | C2 beaconing, exfiltration, DNS tunneling |
  885. | Docker/containerd | Container Analyst | Container escape, image tampering, runtime evidence |
  886. | Memory dumps | Memory Analyst | Process analysis, rootkits, credential artifacts |
  887. | AWS/Azure/GCP | Cloud Analyst | API anomalies, IAM abuse, network-flow evidence |
  888. | File system | Persistence Hunter | Cron, systemd, SSH keys, PAM, kernel modules |
  889. ### Media/Marketing Kit — Campaign Lifecycle
  890. Media/Marketing Kit treats campaign work as a lifecycle with artifacts and
  891. review gates, so strategy, content, legal/brand review, publication planning,
  892. and performance analysis remain inspectable.
  893. ```text
  894. ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
  895. │ STRATEGY │───▶│ CREATION │───▶│ REVIEW │───▶│ PUBLISH │───▶│ ANALYZE │
  896. │ │ │ │ │ │ │ │ │ │
  897. │ Research │ │ Copy │ │ Brand │ │ Schedule │ │ KPIs │
  898. │ Audience │ │ Design │ │ Legal │ │ Channels │ │ Reports │
  899. │ Strategy │ │ Content │ │ Quality │ │ Launch │ │ Learnings│
  900. └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
  901. ```
  902. | Discipline | Example Artifacts |
  903. |------------|-------------------|
  904. | Strategy | Campaign intake, positioning, messaging, audience profile, channel plan |
  905. | Creation | Blog drafts, social posts, email sequences, creative briefs, media kits |
  906. | Review | Brand compliance, legal clearance, accessibility review, claim substantiation |
  907. | Publication | Launch checklist, schedule, channel handoff, go-live readiness |
  908. | Analysis | KPI report, performance digest, retrospective, optimization plan |
  909. ### Media Curator — Archive Management
  910. Media Curator helps assess, acquire, organize, verify, transcribe, and export
  911. media collections. It starts with assessment and planning so unknown or mixed
  912. media is routed before downloads or metadata rewrites.
  913. > Assess my Pink Floyd collection, identify gaps, and suggest sources for the missing material.
  914. >
  915. > Transcribe `/path/to/media.wav` and retain timestamps and source provenance.
  916. >
  917. > Review the collection's tags and completeness, assemble the 1973 live recordings, and prepare a Plex export.
  918. > Verify the archive and report anything unresolved.
  919. Quality tiers help reviewers choose what to keep. Transcript sidecars preserve
  920. source hashes, transcript hashes, timestamps, and optional speaker labels for
  921. review and later research handoff. Common standards include ID3v2.4, Vorbis
  922. Comments, MusicBrainz, PREMIS 3.0, and W3C PROV-O.
  923. ### Research Complete — Academic Research Pipeline
  924. Research Complete turns search results and PDFs into source-grounded,
  925. reviewable research artifacts with persistent identifiers, quality checks, and
  926. provenance.
  927. ```text
  928. ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
  929. │ DISCOVER │───▶│ ACQUIRE │───▶│ DOCUMENT │───▶│ ARCHIVE │
  930. │ │ │ │ │ │ │ │
  931. │ Search │ │ Download │ │ RAG │ │ OAIS │
  932. │ databases│ │ PDF │ │ summaries│ │ lifecycle│
  933. │ Rank │ │ Metadata │ │ Citations│ │ FAIR │
  934. │ results │ │ extract │ │ GRADE │ │ W3C PROV │
  935. └──────────┘ └──────────┘ └──────────┘ └──────────┘
  936. ```
  937. Pipeline stages: Discovery -> Acquisition -> Documentation -> Citation ->
  938. Quality Assessment -> Synthesis -> Gap Analysis -> Archival. The framework uses
  939. `REF-XXX` identifiers, GRADE-style evidence quality labels, FAIR-style checks,
  940. and Unpaywall lookup for open-access discovery. It flags unsupported claims for
  941. review instead of promising error-free summaries.
  942. ### Knowledge Base — Linked Project Wiki
  943. Knowledge Base is for open-ended knowledge accumulation where the taxonomy
  944. emerges over time. It uses entity, concept, source, comparison, and synthesis
  945. pages so future sessions can find what is known, what is missing, and how ideas
  946. connect.
  947. | Page Type | Purpose |
  948. |-----------|---------|
  949. | Entity | A person, company, tool, place, system, or other named thing |
  950. | Concept | A technique, pattern, framework, or idea |
  951. | Source | The evidence layer for claims and summaries |
  952. | Comparison | A decision aid for tools, approaches, vendors, or options |
  953. | Synthesis | A higher-level claim produced by combining multiple sources |
  954. ### Ops Complete — Executable Operations
  955. Ops Complete gives operational procedures a structured envelope: inventory,
  956. capabilities, playbooks, gates, targets, schedules, pipelines, and extensions.
  957. It is useful when procedures must be idempotent, verifiable, and evidence-aware.
  958. ```yaml
  959. apiVersion: ops.aiwg.io/v1
  960. kind: OpsPlaybook
  961. metadata:
  962. name: deploy-auth-stack
  963. namespace: production
  964. spec:
  965. # Desired state
  966. status:
  967. # Observed state written by the executor
  968. ```
  969. Extensions add domain-specific ops support for systems, IT, development
  970. infrastructure, and streaming workflows. See [Ops Complete overview](docs/frameworks/ops-complete/overview.md)
  971. and [Ops evidence governance](https://github.com/jmagly/aiwg/blob/main/docs/ops-evidence-governance.md).
  972. ### Security Engineering — Applied Security Decisions
  973. Security Engineering complements SDLC and forensics by focusing on security
  974. decisions that need explicit assumptions and reviewable tradeoffs.
  975. | Area | Example Use |
  976. |------|-------------|
  977. | Cryptographic primitives | Choose AEAD, KDF, hashing, randomness, and signing patterns for a concrete workload |
  978. | Chain of trust | Map trust anchors, update paths, verification points, and failure modes |
  979. | Authentication factors | Decide factor mix, enrollment, recovery, lockout, and degraded-mode behavior |
  980. | Runtime secret hygiene | Review secret storage, process boundaries, rotation, logging, and local development exposure |
  981. | Supply-chain trust | Review dependency sources, lifecycle scripts, release provenance, SBOMs, and signed artifacts |
  982. | Physical-access threats | Model device seizure, kiosk, lab, field, and hostile-local-user conditions |
  983. | DFIR readiness | Prepare evidence handoff points before an incident occurs |
  984. Install with:
  985. ```bash
  986. aiwg use security-engineering
  987. ```
  988. ### Validation Complete — Focused Validation
  989. Validation Complete provides a small validation workflow surface for teams that
  990. need structured review without adopting a broader lifecycle. Use it where a
  991. project already has its own process but wants AIWG-style validation gates and
  992. reports.
  993. ---
  994. ## Voice Framework — Content Voice Consistency
  995. Voice Framework defines reusable writing profiles and output modes that can be
  996. applied across docs, release notes, campaigns, reports, and internal guidance.
  997. It describes the desired voice directly rather than relying only on banned word
  998. lists.
  999. | Profile | When to Use | Characteristics |
  1000. |---------|-------------|----------------|
  1001. | `technical-authority` | API docs, architecture guides | Precise terminology, direct claims, concrete examples |
  1002. | `friendly-explainer` | Tutorials, onboarding | Accessible language, patient sequencing, light warmth |
  1003. | `executive-brief` | Status reports, proposals | Decision-oriented summaries, concise evidence, clear next steps |
  1004. | `casual-conversational` | Blog posts, social media | Natural rhythm, opinion-forward phrasing, varied structure |
  1005. > Apply the technical-authority voice to `docs/architecture.md`.
  1006. >
  1007. > Create a reusable company voice from `blog-posts/*.md`, and analyze how `docs/existing-content.md` compares.
  1008. >
  1009. > Blend technical-authority and casual-conversational voices at a 70:30 ratio for this draft.
  1010. See [Voice Framework overview](docs/addons/voice-framework/overview.md) and
  1011. [Voice Framework quickstart](docs/addons/voice-framework/quickstart.md).
  1012. ## MCP Server — Model Context Protocol Integration
  1013. AIWG can expose its project context, discovery catalog, and governed workflows through a Model Context Protocol
  1014. server. This lets MCP-capable tools call AIWG without learning the repository layout or memorizing provider-specific
  1015. file locations.
  1016. The MCP server is useful when you want an assistant to ask AIWG questions such as “what capabilities are available for
  1017. release planning?”, “show the SDLC quickstart”, or “run this governed workflow and return the evidence artifact.” The
  1018. base server keeps a small default tool surface; larger toolsets can be enabled explicitly for teams that want richer
  1019. orchestration, mission, dataset, or framework operations.
  1020. > Connect this AI tool to AIWG’s MCP server. Start with the default tool surface; enable flow, mission, and catalog
  1021. > operations when this workspace needs them, and verify the connection.
  1022. Provider installation depends on the host. AIWG can write MCP configuration for supported targets where the provider
  1023. has a stable local MCP config format; other providers use the same server command in their own UI or settings.
  1024. > Configure the AIWG MCP connection for the provider I use in this workspace. Check its supported settings and
  1025. > tell me whether the host needs any further setup.
  1026. MCP integration does not make every AIWG operation model-backed. Catalog reads, status checks, link resolution, and
  1027. local evidence inspection are ordinary local operations. Workflows that ask an assistant to reason, draft, call
  1028. another provider, or continue an agent loop may use model calls depending on the connected host and selected provider.
  1029. See also: [MCP server documentation](docs/mcp/README.md), [MCP capability
  1030. audit](docs/integrations/mcp-capability-audit.md), and [cross-platform
  1031. overview](docs/integrations/cross-platform-overview.md).
  1032. ## Decision Support — Bounded Decisions Offloaded to Jev
  1033. Much of an agent's reasoning goes to small questions with a fixed answer shape: is this test failure flaky, which of
  1034. these four files owns the retry policy, how severe is this finding on a scale of 1 to 5. The optional
  1035. `decision-engine` addon sends those bounded decisions to Jev, a decision service, and returns a typed answer with a
  1036. confidence score. When Jev abstains, times out, is not configured, or falls below the confidence threshold, the
  1037. result is a fallback and the assistant decides as usual.
  1038. > Set up Jev decision offload for this workspace and verify it with one test call. Then triage these failing tests:
  1039. > ask Jev whether each failure is flaky, and show me every answer with its confidence.
  1040. Decision support is opt-in and is not installed by `aiwg use all`. Enabling it takes one addon and one token:
  1041. ```bash
  1042. aiwg use decision-engine
  1043. printf '%s' "$TOKEN" | aiwg decision setup jev --token-stdin --verify
  1044. aiwg decision ask --question "Is this test failure flaky?" --yes-no --context-file test-output.log --json
  1045. ```
  1046. Three answer shapes are supported: `--yes-no`, `--choices` for a pick from known options, and `--scale` for a score
  1047. such as 1–5. The deployed `decision-offload` rule tells agents to try Jev first for these shapes, and never for
  1048. open-ended generation, code, multi-step plans, or anything that authorizes a destructive or outward action. Jev
  1049. output is advisory data, not authorization. Savings vary by workload: offload helps most when a task asks many small
  1050. bounded questions.
  1051. The question and its context are sent to Jev, so keep secrets out of both. The same decision definitions can also run
  1052. through an ordinary LLM-subagent binding when you want rulesets without an external service.
  1053. See the [Jev quickstart](docs/decision/jev-quickstart.md), [normalized decisions and
  1054. rulesets](docs/decision/README.md), and the MCP `decision-ask` tool in the [CLI/MCP driver
  1055. guide](docs/decision/cli-mcp-driver.md).
  1056. ## Agent Evaluation Framework
  1057. AIWG treats agents, skills, commands, and rules as reviewable project assets. The evaluation workflow is designed to
  1058. answer concrete questions before you rely on a capability in a live project:
  1059. - Does the capability declare the right trigger conditions and boundaries?
  1060. - Does it cite the files, schemas, or rules it depends on?
  1061. - Does it produce artifacts that another provider can inspect?
  1062. - Does it fail safely when prerequisites are missing?
  1063. - Does it preserve evidence for audit, handoff, or regression review?
  1064. Ask for an evaluation outcome; the assistant handles capability lookup, metadata validation, and evidence tools.
  1065. > Find the relevant agent-evaluation workflow. Review this capability’s metadata, triggers, dependencies, and
  1066. > evidence contract, then record the checks and any gaps.
  1067. A practical evaluation usually starts with a small task and a pass/fail criterion. For example:
  1068. > Evaluate the release-note drafting capability against this repository. Use only committed changelog entries and
  1069. merged PR metadata. The result is acceptable if every claim links to a source artifact and uncited claims are listed
  1070. separately.
  1071. That prompt-led path is intentional. AIWG can route the work through provider-native tools, but the acceptance
  1072. criterion remains explicit and reviewable. Avoid treating any score, pass rate, or runtime as guaranteed across models
  1073. or providers; those values depend on the selected model, available tools, project size, and the evidence the workflow
  1074. can inspect.
  1075. ## Bidirectional Traceability — @-Mention System
  1076. AIWG uses lightweight `@` references to connect instructions, generated artifacts, source files, evidence, and
  1077. follow-up work. The goal is traceability across providers: a model can move from a rule to the code it governs, from a
  1078. generated report to the source data behind it, or from an issue to the artifact that closed it.
  1079. ```markdown
  1080. <!-- In an agent or skill file -->
  1081. @src/auth/middleware.ts
  1082. @docs/security/authentication.md
  1083. @.aiwg/evidence/release-2026-09-07.json
  1084. ```
  1085. Traceability matters most when a workflow crosses boundaries. An SDLC intake can reference the use case it created. A
  1086. context-firewall review can reference the baseline it approved. A dataset query can reference the source, ingest plan,
  1087. checkpoint, and verification record instead of relying on conversation memory.
  1088. Ask for the traceability result you need; the assistant discovers the relevant validation or reporting tools:
  1089. > Check the references in `docs/` for missing targets and inconsistent links. Save a traceability report with
  1090. > evidence under `.aiwg/reports/`.
  1091. For scripted checks, the [CLI reference](docs/cli/reference.md) documents discovery and artifact lookup.
  1092. Use root-relative references in public documentation so links work from the README. Use provider-specific absolute
  1093. paths only inside generated provider files where that provider requires them.
  1094. ## Configuration & Customization
  1095. AIWG separates project context from provider packaging. The project keeps canonical context and generated artifacts
  1096. under the workspace, then deploys provider-specific adapters for Claude, Codex, Cursor, Windsurf, Warp, OpenCode,
  1097. OpenClaw, OpenHuman, Hermes, DeepSeek Harness, Copilot, Devin, Factory, Oh My Pi, Pi Coding Agent, Antigravity, and
  1098. the generic fallback.
  1099. The primary files are:
  1100. ```text
  1101. WORKSPACE.md # Project/operator context read by providers
  1102. AIWG.md # AIWG discovery and routing guide
  1103. AGENTS.md # Provider bootstrap for Codex and other AGENTS.md readers
  1104. .aiwg/ # Canonical AIWG config, generated context, evidence, reports
  1105. .aiwg/aiwg.config # Workspace configuration and provider deployment state
  1106. .aiwg/index/ # Searchable artifact and capability indexes when generated
  1107. .aiwg/reports/ # Audits, sync reports, doctor reports, workflow outputs
  1108. .aiwg/sessions/ # Optional local session catalog data
  1109. .aiwg/datasets/ # Optional dataset plans, manifests, lineage, and exports
  1110. ```
  1111. Provider directories are generated from the same canonical context. Their exact shape depends on the provider:
  1112. ```text
  1113. .claude/ # Claude Code skills, commands, hooks, settings
  1114. .codex/ or ~/.codex/ # Codex prompts and global configuration where applicable
  1115. .agents/ # Cross-provider agents and skills used by Codex/Antigravity/OMP
  1116. .cursor/ # Cursor rules and skills
  1117. .github/ # GitHub Copilot prompts, instructions, and agents
  1118. .warp/ # Warp skills and compatibility assets
  1119. .omp/ # Oh My Pi native agents, prompts, rules, and bootstrap
  1120. ```
  1121. ### Creating Custom Extensions
  1122. Describe the reusable capability you want. The assistant selects a scaffold for the appropriate asset type and
  1123. validates its metadata and references.
  1124. > Create a custom release-review extension with a reviewer agent, checklist, and release-note skill. Choose the
  1125. > appropriate bundle structure, define inputs and outputs, and validate it before deployment.
  1126. A custom extension should define the smallest durable contract needed by the workflow: triggers, inputs, outputs,
  1127. evidence, and provider packaging. Keep model-specific phrasing in provider assets. Keep project policy, schemas, and
  1128. reusable workflow contracts in `.aiwg` or extension source so multiple providers can share them.
  1129. ### Capability Discovery — Describe the Task
  1130. The assistant searches AIWG’s capability graphs from your intent, then reads the matching assets. You can name the
  1131. outcome without knowing the command, skill, agent, or framework that implements it.
  1132. > Find the appropriate workflow for production deployment, dataset lineage, or project intake. Show why it fits
  1133. > this task, read the selected instructions, and use our indexed custom assets where relevant.
  1134. Discovery is also useful for documentation. Instead of hard-coding every command in a README, link to the relevant
  1135. quickstart and show one or two representative prompts. The catalog can change as frameworks and addons are installed,
  1136. while the task language stays stable.
  1137. ### Artifact Index — Find and Reuse Project Work
  1138. The artifact index makes generated work easier to find, verify, and reuse. It indexes reports, generated context,
  1139. evidence, and other AIWG-managed files into a searchable local catalog.
  1140. > Refresh the artifact index, verify that this workspace is connected, and find the latest review evidence.
  1141. A provider can then answer questions such as “find the latest context-firewall report” or “show the SDLC artifact that
  1142. introduced this acceptance criterion” without scanning the whole repository manually.
  1143. ### Doc Sync — Bidirectional Documentation
  1144. Doc sync is for keeping code and documentation aligned under review. It can audit mismatches, propose updates, and
  1145. write reports before code or documentation changes are accepted.
  1146. > Audit the documentation against the code without changing either. Identify stale quickstarts and missing
  1147. > implementation requirements, then propose scoped updates with source references.
  1148. Doc sync writes reports under `.aiwg/working/` and `.aiwg/reports/` when configured. Treat those reports as review
  1149. artifacts. Do not assume doc sync can prove semantic equivalence between code and prose; it identifies
  1150. inconsistencies, stale examples, missing links, and candidate updates for human or provider review.
  1151. ### Reproducibility Validation
  1152. AIWG’s reproducibility features focus on explicit inputs, evidence records, deterministic modes where available, and
  1153. reviewable outputs. They do not guarantee identical model text across providers or runs.
  1154. > Run this workflow with explicit inputs and a reproducible seed where supported. Export its evidence, verify
  1155. > the bundle, and report anything that cannot be reproduced.
  1156. For workflows that expose checkpointing, snapshots, or replay through installed skills, start with discovery so the
  1157. current workspace selects the correct implementation:
  1158. > Find the supported checkpoint and replay workflow for this workspace, preserve the current state, and explain
  1159. > what a later run can verify or resume.
  1160. The practical standard is repeatability of inputs, citations, commands, and artifacts. Exact model wording should be
  1161. treated as a generated output, not as the source of truth.
  1162. ### Session Catalog
  1163. The session catalog is an optional local feature for importing, searching, and promoting useful provider conversation
  1164. history. It is designed for controlled handoff and audit. It should be enabled intentionally because it can include
  1165. sensitive prompts, local paths, and project context.
  1166. > Set up a local session catalog for this workspace. Preview the provider sessions available for import, import
  1167. > the reviewed selection, and find conversations about release blockers with their provenance.
  1168. Discovery reports each provider's coverage, so a missing history shows as a gap that needs an export or an authorized
  1169. root, not as proof of no activity. Imported sessions can be tagged, extracted into reusable notes, reviewed for
  1170. promotion, or audited for provenance.
  1171. Keep private-provider roots and shared history locations explicit in configuration; do not assume another provider’s
  1172. global history is safe to import by default.
  1173. See [session history setup](docs/getting-started/session-history.md) and [sessions CLI](docs/sessions/cli.md).
  1174. ### Dataset Intelligence
  1175. Dataset intelligence gives AIWG a governed path for local files, directories, CSV/JSONL sources, and approved HTTP
  1176. sources. The dataset router carries stable source, plan, checkpoint, lineage, verification, and export references
  1177. between phases.
  1178. > Build a governed index of these documentation sources. Validate and preview the inputs, prepare an ingestion
  1179. > plan, and retain its approval, lineage, and verification records. Then find which quickstart explains Codex setup.
  1180. Local adapters are constrained by configured roots. HTTP adapters are deny-by-default and require explicit hosts.
  1181. Indexes are derived artifacts; the canonical record is the source descriptor, approved plan, ingest run, and evidence
  1182. trail.
  1183. See [dataset intelligence quickstart](docs/addons/dataset-intelligence/quickstart.md), [dataset
  1184. overview](docs/addons/dataset-intelligence/overview.md), and [source adapters](docs/dataset/source-adapters.md).
  1185. ## Issue-Driven Development
  1186. AIWG supports local issue planning and governed handoff to external issue trackers. The local issue CLI stores records
  1187. under `.aiwg/issues/`, which makes issues reviewable even when a project does not have GitHub, Gitea, Jira, or another
  1188. tracker connected.
  1189. > Set up local issues with the APP prefix. Draft an issue for OAuth2 callback validation, including state checks,
  1190. > token-exchange errors, and tests. Show the open authentication issues and record verified progress.
  1191. External tracker import/export is explicit. Use it when you need traceability between local AIWG records and a remote
  1192. system, and keep snapshots or live connector settings under review.
  1193. > Import this GitHub issue snapshot into our local store. Prepare APP-0001 for the Gitea tracker and show any
  1194. > conflicts between local and external state before reconciling them.
  1195. For agent-assisted repair work, name the issues and acceptance checks:
  1196. > Resolve APP-0001 and APP-0002 using this project's issue workflow. Run the project's test and lint checks, and
  1197. > report the changes and anything unresolved.
  1198. External issue systems are not a default side effect of local issue work. They require configured connectors, snapshots,
  1199. or explicit export/import requests. See [local issue integration](docs/local-issues.md) and [filing
  1200. issues](docs/contributing/filing-issues.md).
  1201. ## Daemon Mode & Messaging Integration
  1202. AIWG’s automation layer is for long-running coordination, not for hiding work from review. The safe default is local,
  1203. explicit execution with visible status and evidence. Daemon, messaging, and mission-control setups should declare
  1204. their trigger source, operator identity, workspace, budget limits, and completion criteria.
  1205. The base CLI exposes current orchestration commands through the agent loop and mission control. Messaging bridges and chat bots
  1206. are advanced deployments described in the daemon and messaging docs; they require external service configuration and
  1207. should not be assumed to exist in a fresh checkout.
  1208. > Coordinate the release follow-up with at most three concurrent missions. Fix the authentication test failures,
  1209. > retain verification evidence, and show progress. Make it possible to pause, resume, or stop the work.
  1210. For provider messaging, document the concrete external channel and approval boundary. A Slack, Discord, Telegram, or
  1211. webhook bridge should make it clear who can enqueue work, where logs are stored, and which operations require human
  1212. approval before writing to external systems.
  1213. See [daemon guide](docs/daemon-guide.md), [messaging guide](docs/messaging-guide.md), and [Mission Control](docs/addons/agent-loop/quickstart.md).
  1214. ## See It In Action
  1215. The fastest way to use AIWG is to ask for the first useful task, request a concrete deliverable, and name the success
  1216. check. The assistant discovers the relevant skill or provider surface and handles the underlying tools.
  1217. ### SDLC workflow from idea to implementation
  1218. > Use the SDLC framework to turn an AI-powered code review tool into requirements, architecture decisions, a
  1219. > first implementation task, and acceptance checks. Return links to the generated artifacts.
  1220. ### Long-running implementation loop
  1221. > Fix the failing authentication tests in a bounded loop. Stop after five iterations or forty-five minutes, and
  1222. > report whether the relevant tests pass and what remains unresolved.
  1223. The agent loop is useful for bounded repair loops where the success condition is objective. It is not a guarantee that the
  1224. model will solve the task. Set wall-clock, token, tool-call, or cost limits for expensive providers.
  1225. ### Recursive search over large code or docs
  1226. > Search the provider quickstarts for outdated reload instructions. Use at most four parallel workers and a
  1227. > 50,000-token budget; return source links, the quoted statements, and proposed corrections.
  1228. ### Bounded decisions without a full reasoning pass
  1229. > Triage these twelve open findings. Ask Jev for a 1–5 severity on each with the finding text as context, show
  1230. > every answer with its confidence, and decide the ones that fall back yourself.
  1231. Dataset-backed knowledge and session history reuse have their own sections under [Configuration &
  1232. Customization](#configuration--customization).
  1233. ### Security, forensics, and operations prompts
  1234. ```text
  1235. Use the security-engineering framework to review the OAuth2 callback flow. Produce threat assumptions, concrete findings, and tests I can run.
  1236. Use the forensics framework to analyze these logs. Preserve evidence references, build a timeline, and separate confirmed facts from hypotheses.
  1237. Use the ops framework to turn this production incident into a runbook update, verification checklist, and follow-up issues.
  1238. ```
  1239. These prompts preserve the original README’s hands-on style while keeping provider behavior accurate: AIWG selects
  1240. framework capabilities through discovery and provider deployment, and the deliverable remains explicit.
  1241. ## Platform Support
  1242. AIWG has registry-backed named provider integrations plus a generic fallback for tools that read Markdown context but
  1243. do not have a dedicated adapter. The integrations share product framing: reusable project context and specialist
  1244. workflows in the AI tools teams already use. Provider distinctions matter because each host has different native
  1245. surfaces.
  1246. See [cross-platform overview](docs/integrations/cross-platform-overview.md) for the maintained comparison and setup links.
  1247. | Provider | Setup | Primary context | Native or conventional surfaces | Notes |
  1248. |---|---|---|---|---|
  1249. | Claude Code | `aiwg use all --provider claude` | `CLAUDE.md` | Skills, commands, hooks, MCP config | Best fit for rich AIWG provider packaging. See [Claude quickstart](docs/integrations/claude-code-quickstart.md). |
  1250. | Codex | `aiwg use all --provider codex` | `AGENTS.md` | Global prompts, project skills, MCP config | Uses AGENTS.md bootstrap plus `.agents/skills/`. See [Codex quickstart](docs/integrations/codex-quickstart.md). |
  1251. | Cursor | `aiwg use all --provider cursor` | Rules and skills | `.cursor/rules/*.mdc`, `.cursor/skills/*/SKILL.md`, `.cursor/hooks.json` | Cursor rules are native; the prompt-discovery hook runs where Cursor runs project hooks. Cursor can also be a direct worker alongside Codex and Muse. See [Cursor quickstart](docs/integrations/cursor-quickstart.md). |
  1252. | OpenCode | `aiwg use all --provider opencode` | Agent/rule context | Provider-local agents, commands, rules | Good for lightweight terminal workflows. |
  1253. | GitHub Copilot | `aiwg use all --provider copilot` | `.github` assets | Prompts, instructions, agents, MCP config | Uses `.github/prompts/*.prompt.md`, `.github/instructions/*.instructions.md`, and `.github/agents/*.agent.md`. |
  1254. | Devin Desktop | `aiwg use all --provider devin` | `AGENTS.md` | Rules and workflows | Formerly Windsurf; `windsurf` remains the provider id and `devin` is its alias. See [quickstart](docs/integrations/windsurf-quickstart.md). |
  1255. | DeepSeek Harness | `aiwg use all --provider dsh` | `AGENTS.md` | Provider-local skills and context | Experimental. See [DeepSeek Harness docs](docs/providers/deepseek-harness.md). |
  1256. | Factory | `aiwg use all --provider factory` | Factory context | Agents and commands where supported | Provider behavior depends on the installed Factory environment. |
  1257. | Hermes | `aiwg use all --provider hermes` | `AGENTS.md` | Skills, with context aggregated into `AGENTS.md` | See [Hermes quickstart](docs/integrations/hermes-quickstart.md). |
  1258. | OpenClaw | `aiwg use all --provider openclaw` | `AGENTS.md` | Native agents, skills, rules, and commands | User-scope deployment. See [OpenClaw quickstart](docs/integrations/openclaw-quickstart.md). |
  1259. | OpenHuman | `aiwg use all --provider openhuman` | Provider-managed | Skills, with other assets indexed | Experimental. See [OpenHuman quickstart](docs/integrations/openhuman-quickstart.md). |
  1260. | Warp Terminal | `aiwg use all --provider warp` | `WARP.md` | Skills, with context aggregated into `WARP.md` | See [Warp quickstart](docs/integrations/warp-terminal-quickstart.md). |
  1261. | Grok Bot | `aiwg use all --provider grokbot` | `AGENTS.md` | Discover-first; native skills with `--scope user` and `AIWG_GROKBOT_SKILLS_DIR` | Stable; not Cursor / not xAI Grok Build. See [Grok Bot reference](docs/agents/providers/grokbot.md). |
  1262. | Grok Build | `aiwg use all --provider grok-build` | `WORKSPACE.md` via generated `AGENTS.md` | `.grok/skills/` kernel; `$GROK_HOME` user skills | Experimental; distinct from Grok Bot and Grok web Build. [Quickstart](docs/integrations/grok-build-quickstart.md), [reference](docs/agents/providers/grok-build.md), [qualification](docs/providers/grok-build-qualification.md). |
  1263. | Muse Code | `aiwg use all --provider muse` | `AGENTS.md` | `.agents/skills/` project; XDG user root at deploy time | Stable; no aliases. See [Muse quickstart](docs/integrations/muse-quickstart.md). |
  1264. | Oh My Pi | `aiwg use all --provider omp` | `.omp/AGENTS.md` | Agents, prompts, rules, skills | Dedicated OMP quickstart: [Oh My Pi quickstart](docs/providers/omp.md). |
  1265. | Pi Coding Agent | `aiwg use all --provider pi` | `AGENTS.md` | Agent Skills, prompt templates, trust-gated extension bridge | Experimental; see [Pi quickstart](docs/integrations/pi-quickstart.md). |
  1266. | Antigravity | `aiwg use all --provider antigravity` | `AGENTS.md` and `.agents/` | Agents, skills, indexed commands, MCP config when enabled | See [Antigravity provider docs](docs/providers/antigravity.md). |
  1267. | Flue | `aiwg use sdlc --provider flue` | Inline `AGENTS.md` | Kernel `.agents/skills/`, SQLite `db.ts` | Experimental app target. [Reference](docs/providers/flue.md). |
  1268. | Generic Markdown | `aiwg use all --provider generic` | `AIWG.md` / `WORKSPACE.md` | Markdown instructions | Use when a provider reads repo docs but has no dedicated integration. |
  1269. For CI jobs, [build verification](docs/integrations/build-verify.md) checks
  1270. deployment and provider discovery before the provider runs a task. For routines,
  1271. teammates, connectors, or memory proposals, [bot handoffs](docs/integrations/bot-handoff.md)
  1272. produce a draft to review in the selected provider.
  1273. After deployment, check readiness with the assistant or run the health check:
  1274. ```bash
  1275. aiwg doctor
  1276. ```
  1277. > Confirm that the deployed provider context is active and explain any remaining setup steps.
  1278. Fresh deployments may report that the provider should be restarted or reloaded so the host notices new files. That is
  1279. provider-specific readiness information, not a requirement to regenerate context after every command.
  1280. ## CLI Reference
  1281. Everyday work stays in the conversation. The small manual command set is for setup and maintenance:
  1282. | Command | Purpose |
  1283. | --- | --- |
  1284. | `aiwg use <framework> --provider <provider>` | Deploy and connect AIWG assets to the project. |
  1285. | `aiwg init` | Create the baseline project configuration; deployment can initialize it when needed. |
  1286. | `aiwg refresh` | Update AIWG and refresh deployed project assets. |
  1287. | `aiwg doctor` | Diagnose installation and workspace readiness. |
  1288. Installing the executable still requires a package manager, as shown in [Quick Start](#quick-start); an assistant with
  1289. terminal access can perform that step too. Advanced scripting, server configuration, registry operations, indexing,
  1290. session history, decision offload, issue synchronization, and automation options belong in the [CLI
  1291. reference](docs/cli/reference.md) and linked guides. You do not need to learn those interfaces to request their
  1292. outcomes.
  1293. ## Architecture
  1294. AIWG is a portable context and workflow layer. It keeps canonical project instructions in repo-visible files, packages
  1295. provider-specific assets for the AI tools a team uses, and preserves artifacts so work can be reviewed outside the
  1296. original chat.
  1297. ```mermaid
  1298. flowchart TD
  1299. A[Project context<br/>WORKSPACE.md + AIWG.md] --> B[AIWG catalog]
  1300. B --> C[Provider packaging]
  1301. C --> D[Claude, Codex, Cursor, Copilot, Warp, OMP, Antigravity, others]
  1302. B --> E[Specialist workflows]
  1303. E --> F[SDLC, research, ops, security, marketing, datasets, RLM]
  1304. E --> G[Artifacts and evidence]
  1305. G --> H[Reports, issues, datasets, sessions, indexes]
  1306. H --> B
  1307. ```
  1308. ### Extension System
  1309. An AIWG extension usually contains some combination of:
  1310. | Asset | Role |
  1311. |---|---|
  1312. | Agents | Persistent role definitions, responsibilities, and routing constraints. |
  1313. | Skills | Task-specific procedures with triggers, inputs, outputs, and evidence rules. |
  1314. | Commands | Provider-facing shortcuts or prompt templates. |
  1315. | Rules | Policies and reusable constraints. |
  1316. | Schemas | Structured contracts for plans, artifacts, manifests, and reports. |
  1317. | Templates | Repeatable starting points for generated files. |
  1318. | Scripts | Local deterministic helpers used by workflows. |
  1319. The registry and discovery index make those assets findable without requiring every provider to support every asset
  1320. type natively. When a provider lacks a native concept, AIWG packages the asset as Markdown context or a conventional
  1321. file the provider can read.
  1322. ### Multi-Agent Orchestration
  1323. AIWG’s orchestration model is explicit about roles and handoffs. A complex task can move through a steward, specialist
  1324. skill, review step, evidence export, and follow-up issue without losing the artifact trail.
  1325. ```mermaid
  1326. sequenceDiagram
  1327. participant U as User
  1328. participant S as Steward / Discover
  1329. participant W as Specialist Workflow
  1330. participant P as Provider Tooling
  1331. participant E as Evidence Store
  1332. U->>S: Describe outcome and success check
  1333. S->>W: Select capability and inputs
  1334. W->>P: Execute provider-local or CLI steps
  1335. P-->>W: Results, files, diagnostics
  1336. W->>E: Write report/evidence/issue refs
  1337. W-->>U: Deliverable with checks and next step
  1338. ```
  1339. This structure is why AIWG documentation emphasizes “first useful task, concrete deliverable, success check, and next
  1340. step.” It gives a model enough direction to act while leaving a reviewer enough evidence to verify the result.
  1341. ### YAML Metalanguage
  1342. Many AIWG assets use YAML frontmatter or YAML schemas so capabilities can be discovered, validated, and converted
  1343. between provider formats.
  1344. ```yaml
  1345. ---
  1346. namespace: aiwg
  1347. name: release-notes
  1348. description: Draft release notes from approved issue and changelog artifacts
  1349. platforms: [all]
  1350. triggers:
  1351. - release notes
  1352. - changelog summary
  1353. outputs:
  1354. - docs/releases/{version}.md
  1355. evidence:
  1356. required:
  1357. - source_issue_refs
  1358. - changelog_refs
  1359. ---
  1360. ```
  1361. The metadata is not decorative. It lets discovery find the capability, lets validation detect missing fields,
  1362. and gives provider adapters enough information to package the asset accurately.
  1363. ### Project Artifacts
  1364. AIWG-generated artifacts are intentionally ordinary files: Markdown, JSON, YAML, SQLite-backed local stores when
  1365. enabled, and provider-readable context. That makes them inspectable in a code review and portable across machines.
  1366. Examples include:
  1367. ```text
  1368. .aiwg/reports/context-firewall-*.md
  1369. .aiwg/reports/doc-sync-audit-*.md
  1370. .aiwg/evidence/*.json
  1371. .aiwg/issues/*.json
  1372. .aiwg/datasets/**/manifest.json
  1373. .aiwg/rlm-prep/**/manifest.json
  1374. .aiwg/sessions/**
  1375. ```
  1376. Artifact indexes reduce manual browsing, but they do not replace source review. Treat indexed results as navigation
  1377. aids with links back to the original files.
  1378. ## Agent Loop — Autonomous Long-Running Agent Orchestration
  1379. The agent loop is AIWG’s bounded iterative execution mode. It is intended for tasks where the objective and completion criterion
  1380. can be checked: fixing tests, applying a migration, updating docs to match a report, or carrying a refactor through
  1381. verification.
  1382. > Update the provider quickstarts from the approved marketing audit. Verify Markdown links and keep changes
  1383. > within scope. Stop after six iterations, sixty minutes, or 120 tool calls.
  1384. The agent loop records loop state so work can be inspected and resumed when supported by the selected provider and local environment.
  1385. > Show the current loop’s progress and evidence. Resume its saved work if interrupted, or stop it when I ask.
  1386. Use budgets for any loop that may call a remote model or external provider:
  1387. > Reduce flaky integration tests and retain first-attempt failures. Verify the reproduction over ten consecutive
  1388. > runs, with a limit of 200,000 tokens and $10. Stop when either budget is exhausted.
  1389. Long-running automation should still produce reviewable outputs: changed files, reports, evidence, status logs, and
  1390. the exact checks run. The agent loop can continue work within configured limits, but it cannot guarantee a solution, fixed
  1391. runtime, or provider availability.
  1392. Mission Control builds on the same principle for multiple bounded work items:
  1393. > Coordinate the documentation-audit follow-up with at most four concurrent missions. Check that the README’s
  1394. > examples are current, preserve evidence, and report progress and unresolved findings.
  1395. ## RLM — Recursive Context Decomposition
  1396. For a bounded batch, specify the parallelism limit explicitly:
  1397. > Add TypeScript types to the components in `src/components/*.tsx`. Work in bounded batches with at most four
  1398. > parallel workers, and verify each batch.
  1399. RLM helps with sources that are too large to fit comfortably in one model context. It prepares files into traceable
  1400. chunks, fans a query out across those chunks, and merges results with links back to the source material.
  1401. ```mermaid
  1402. flowchart LR
  1403. A[Source files] --> B[rlm-prep]
  1404. B --> C[manifest.json]
  1405. C --> D[rlm-search / fanout]
  1406. D --> E[ranked findings]
  1407. E --> F[source-linked answer]
  1408. C --> G[rlm-cache]
  1409. ```
  1410. Ask to prepare a file tree once when you want to reuse it for several searches.
  1411. > Prepare the source and documentation for repeated searches. Find where provider reload status is calculated
  1412. > and summarize stale quickstart instructions, using at most four parallel workers and source-linked findings.
  1413. For a single-file review:
  1414. > Divide this README into reviewable chunks with source locations and enough overlap to preserve context.
  1415. RLM is a retrieval and decomposition workflow, not a magic context override. Quality depends on chunk boundaries,
  1416. source coverage, prompt specificity, model capability, and budget. For high-stakes review, ask for quoted source
  1417. links, inspect the cited chunks, and rerun targeted searches for disputed claims.
  1418. ## Research Foundations
  1419. AIWG draws design ideas from research across cognitive science, multi-agent
  1420. systems, software engineering, retrieval, provenance, and AI safety. The
  1421. results cited below belong to the referenced papers or systems; they are not
  1422. AIWG performance guarantees. Reference summaries live in `docs/references/`
  1423. (REF-NNN entries). The bibliography groups related design topics.
  1424. ### Cognitive Foundations
  1425. - Miller, G.A. (1956). [The Magical Number Seven, Plus or Minus Two](https://doi.org/10.1037/h0043158). *Psychological Review*, 63(2), 81–97. doi:10.1037/h0043158
  1426. - Sweller, J. (1988). [Cognitive Load During Problem Solving: Effects on Learning](https://doi.org/10.1207/s15516709cog1202_4). *Cognitive Science*, 12(2), 257–285. doi:10.1207/s15516709cog1202_4
  1427. - Anderson, J.R. et al. (2004). [An Integrated Theory of the Mind](https://doi.org/10.1037/0033-295X.111.4.1036). *Psychological Review*, 111(4), 1036–1060. (ACT-R cognitive architecture)
  1428. - Laird, J.E., Newell, A. & Rosenbloom, P.S. (1987). [SOAR: An Architecture for General Intelligence](https://doi.org/10.1016/0004-3702(87)90050-6). *Artificial Intelligence*, 33(1), 1–64.
  1429. - Harel, D. (1987). [Statecharts: A Visual Formalism for Complex Systems](https://doi.org/10.1016/0167-6423(87)90035-9). *Science of Computer Programming*, 8(3), 231–274.
  1430. - Young, S. et al. (2010). [The Hidden Information State Model: A Practical Framework for POMDP-Based Spoken Dialogue Management](https://doi.org/10.1016/j.csl.2009.04.001). *Computer Speech & Language*, 24(2), 150–174.
  1431. ### Multi-Agent Systems & Orchestration
  1432. - Jacobs, R.A. et al. (1991). [Adaptive Mixtures of Local Experts](https://doi.org/10.1162/neco.1991.3.1.79). *Neural Computation*, 3(1), 79–87. (Mixture-of-Experts foundation)
  1433. - Hong, S. et al. (2024). [MetaGPT: Meta Programming for a Multi-Agent Collaborative
  1434. Framework](https://arxiv.org/abs/2308.00352). *ICLR 2024*.
  1435. - Qian, C. et al. (2024). [ChatDev: Communicative Agents for Software Development](https://arxiv.org/abs/2307.07924). *ACL 2024*.
  1436. - Shen, Y. et al. (2023). [HuggingGPT: Solving AI Tasks with ChatGPT and its Friends in HuggingFace](https://arxiv.org/abs/2303.17580). *NeurIPS 2023*.
  1437. - Tao, W. et al. (2024). [MAGIS: LLM-Based Multi-Agent Framework for GitHub Issue Resolution](https://arxiv.org/abs/2403.17927).
  1438. - Zhang, J. et al. (2025). [AFlow: Automating Agentic Workflow Generation](https://arxiv.org/abs/2410.10762). *ICLR
  1439. 2025 Oral*.
  1440. - Wu, Q. et al. (2023). [AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation](https://arxiv.org/abs/2308.08155). (Conversational multi-agent framework)
  1441. - Yu, C. et al. (2025). [A Survey on Agent Workflow — Status and Future](https://arxiv.org/abs/2508.01186). (24 systems, 11 metrics)
  1442. - Lodha, D. et al. (2026). [MCP-Diag: A Deterministic, Protocol-Driven Architecture for AI-Native Network
  1443. Diagnostics](https://arxiv.org/abs/2601.22633). *COMSNETS 2026*.
  1444. - Yu, G. (2026). [AdaptOrch: Adaptive Orchestration for Multi-Agent LLM Systems Through Topology-Aware Task Planning](https://arxiv.org/abs/2502.09340).
  1445. - Gerred (2025). [Multi-Agent Orchestration](https://gerred.github.io/building-an-agentic-system/second-edition/part-iv-advanced-patterns/chapter-10-multi-agent-orchestration.html). Tool isolation, resource boundaries, observable coordination.
  1446. - Falconer, S. (2025). [Event-Driven Multi-Agent Systems](https://www.confluent.io/blog/event-driven-multi-agent-systems/). Confluent. 4 Kafka orchestration patterns.
  1447. - Mario, M. (2025). [Multi-Agent System Patterns: A Unified Guide to Designing Agentic Architectures](https://medium.com/@mjgmario/multi-agent-system-patterns-a-unified-guide-to-designing-agentic-architectures-04bb31ab9c41). 4-dimensional framework.
  1448. - Runkle, S. (2026). [Choosing the Right Multi-Agent
  1449. Architecture](https://www.blog.langchain.com/choosing-the-right-multi-agent-architecture/). LangChain. Subagents,
  1450. skills, and handoffs.
  1451. - Towards Data Science (2025). [Why Your Multi-Agent System Is Failing: Escaping the 17x Error
  1452. Trap](https://towardsdatascience.com/why-your-multi-agent-system-is-failing-escaping-the-17x-error-trap-of-the-bag-of-agents/).
  1453. Coordination failure analysis.
  1454. - NexAI Tech (2025). [Multi-AI Agent Architecture Patterns for Scale](https://nexaitech.com/multi-ai-agent-architecutre-patterns-for-scale/). Enterprise 5-layer architecture, 3 orchestration patterns.
  1455. - Wexford, E. (2026). [How to Build Multi-Agent Systems: Complete 2026
  1456. Guide](https://dev.to/eira-wexford/how-to-build-multi-agent-systems-complete-2026-guide-1io6). DEV Community.
  1457. Multi-agent design guidance.
  1458. ### Reasoning & Planning
  1459. - Wei, J. et al. (2022). [Chain-of-Thought Prompting Elicits Reasoning in Large Language Models](https://arxiv.org/abs/2201.11903). *NeurIPS 2022*.
  1460. - Wang, X. et al. (2023). [Self-Consistency Improves Chain of Thought Reasoning in Language Models](https://arxiv.org/abs/2203.11171). *ICLR 2023*.
  1461. - Yao, S. et al. (2023). [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629). *ICLR 2023*.
  1462. - Yao, S. et al. (2023). [Tree of Thoughts: Deliberate Problem Solving with Large Language Models](https://arxiv.org/abs/2305.10601). *NeurIPS 2023*.
  1463. - Zhou, A. et al. (2024). [Language Agent Tree Search Unifies Reasoning, Acting, and Planning in Language Models](https://arxiv.org/abs/2310.04406). *ICML 2024*.
  1464. - Kojima, T. et al. (2022). [Large Language Models are Zero-Shot Reasoners](https://arxiv.org/abs/2205.11916). *NeurIPS 2022*. ("Let's think step by step")
  1465. - Liu, Z. et al. (2026). [Exploratory Memory-Augmented LLM Agent via Hybrid On- and Off-Policy Optimization
  1466. (EMPO²)](https://arxiv.org/abs/2602.23008). *ICLR 2026*.
  1467. ### Self-Correction & Iterative Refinement
  1468. - Madaan, A. et al. (2023). [Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.17651).
  1469. *NeurIPS 2023*.
  1470. - Shinn, N. et al. (2023). [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366). *NeurIPS 2023*.
  1471. ### Stage-Gate, SDLC & Traceability
  1472. - Cooper, R.G. (1990). [Stage-Gate Systems: A New Tool for Managing New Products](https://doi.org/10.1016/0007-6813(90)90040-I). *Business Horizons*, 33(3), 44–54.
  1473. - Jacobson, I., Booch, G. & Rumbaugh, J. (1999). *The Unified Software Development Process*. Addison-Wesley. ISBN 978-0-201-57169-1.
  1474. - Gotel, O.C.Z. & Finkelstein, A.C.W. (1994). [An Analysis of the Requirements Traceability Problem](https://doi.org/10.1109/ICRE.1994.292398). *IEEE ICRE 1994*.
  1475. ### Software Engineering & Agent-Computer Interface
  1476. - Jimenez, C.E. et al. (2024). [SWE-bench: Can Language Models Resolve Real-world GitHub Issues?](https://www.swebench.com). *ICLR 2024*.
  1477. - Wang, X. et al. (2024). [Executable Code Actions Elicit Better LLM Agents
  1478. (CodeAct)](https://arxiv.org/abs/2402.01030). *ICML 2024*.
  1479. - Yang, J. et al. (2024). [SWE-agent: Agent-Computer Interfaces Enable Automated Software
  1480. Engineering](https://arxiv.org/abs/2405.15793). *NeurIPS 2024*.
  1481. - Laurent, A. (2025). [A Comparison of AI Code Assistants for Large
  1482. Codebases](https://intuitionlabs.ai/articles/ai-code-assistants-large-codebases). IntuitionLabs.
  1483. - Augment Code (2025). [AI Coding Assistants for Large Codebases: A Complete Guide](https://www.augmentcode.com/tools/ai-coding-assistants-for-large-codebases-a-complete-guide).
  1484. - AlgoMaster (2025). [How to Use AI Effectively in Large Codebases](https://blog.algomaster.io/p/using-ai-effectively-in-large-codebases). Retrieval as bottleneck framing.
  1485. ### Context Engineering & Memory
  1486. - Liu, N.F. et al. (2024). [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172). *TACL* 12, 157–173. doi:10.1162/tacl_a_00638
  1487. - Dai, Y. et al. (2025). [Pretraining Context Compressor for Large Language Models with Embedding-Based Memory](https://aclanthology.org/2025.acl-long.1394.pdf). *ACL 2025*.
  1488. - Kang, M. et al. (2025). [ACON: Optimizing Context Compression for Long-Horizon LLM Agents](https://arxiv.org/abs/2510.00615).
  1489. - Liu, F. & Qiu, H. (2025). [Context Cascade Compression (C3): Exploring the Upper Limits of Text Compression](https://arxiv.org/abs/2511.15244).
  1490. - Vasilopoulos, A. (2026). [Codified Context: Infrastructure for AI Agents in a Complex Codebase](https://arxiv.org/abs/2602.20478). (Three-tier context infrastructure: constitution + 19 agents + 34-doc KB)
  1491. - Ostby, D.L. (2025). [Stingy Context: Compressing Code Context for Cost-Effective AI Development Assistance](https://arxiv.org/abs/2512.15504). (TREEFRAG, 18:1 compression ratio)
  1492. - Anthropic Applied AI Team (2026). [Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). Anthropic Engineering Blog.
  1493. - Huang, J.Y. et al. (2026). [Do LLMs Benefit From Their Own Words?](https://arxiv.org/abs/2602.24287)
  1494. - Böckeler, B. (2026). [Context Engineering for Coding Agents](https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html). Martin Fowler's Blog. Two-category framework.
  1495. - Haseeb, M. (2025). [Context Engineering for Multi-Agent LLM Code Assistants](https://arxiv.org/abs/2508.08322).
  1496. - Verma, N. (2026). [Focus Agent: LLM Agent with Active Context Compression for SWE-Bench](https://arxiv.org/abs/2501.09067).
  1497. - Zylos Research (2026). [Long-Running AI Agents and Task Decomposition](https://zylos.ai/research/2026-01-16-long-running-ai-agents). (35-min degradation threshold, Planner-Worker model)
  1498. - Zylos Research (2026). [LLM Context Window Management and Long-Context Strategies](https://zylos.ai/research/2026-01-19-llm-context-management).
  1499. ### Agent Memory & Knowledge Systems
  1500. - Laird, J.E. et al. (1987). [SOAR: An Architecture for General Intelligence](https://doi.org/10.1016/0004-3702(87)90050-6). *Artificial Intelligence*, 33(1), 1–64.
  1501. - Anderson, J.R. et al. (2004). [An Integrated Theory of the Mind (ACT-R)](https://doi.org/10.1037/0033-295X.111.4.1036). *Psychological Review*, 111(4), 1036–1060.
  1502. - Park, J.S. et al. (2023). [Generative Agents: Interactive Simulacra of Human Behavior](https://arxiv.org/abs/2304.03442). *UIST 2023*. doi:10.1145/3586183.3606763
  1503. - Xu, W. et al. (2025). [A-MEM: Agentic Memory for LLM Agents](https://arxiv.org/abs/2502.12110).
  1504. - Hu, Y. et al. (2025). [Memory in the Age of AI Agents: A Survey](https://arxiv.org/abs/2512.13564). (Surveys 100+ implementations, forms-functions-dynamics framework)
  1505. - Rezazadeh, A. et al. (2025). [Collaborative Memory: Multi-User Memory Sharing in LLM Agents with Dynamic Access Control](https://arxiv.org/abs/2505.18279).
  1506. - Yuen, S. et al. (2025). [Intrinsic Memory Agents: Heterogeneous Multi-Agent LLM Systems through Structured Contextual Memory](https://arxiv.org/abs/2508.08997). Role-aligned heterogeneous memory.
  1507. - Graves, A., Wayne, G. & Danihelka, I. (2014). [Neural Turing Machines](https://arxiv.org/abs/1410.5401). External memory architectures.
  1508. - Packer, C. et al. (2023). [MemGPT: Towards LLMs as Operating Systems](https://arxiv.org/abs/2310.08560). OS-inspired virtual context paging.
  1509. - Yu, Z. et al. (2026). [Multi-Agent Memory from a Computer Architecture Perspective](https://arxiv.org/abs/2603.10062). *Architecture 2.0 '26*. Three-layer I/O-cache-memory hierarchy.
  1510. - Chhikara, P. et al. (2025). [Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory](https://arxiv.org/abs/2504.19413).
  1511. ### Recursive Context Decomposition
  1512. - Zhang, A.L., Kraska, T. & Khattab, O. (2026). [Recursive Language Models](https://arxiv.org/abs/2512.24601).
  1513. *arXiv:2512.24601*. MIT CSAIL.
  1514. ### Provenance, Reproducibility & Research Management
  1515. - Wilkinson, M.D. et al. (2016). [The FAIR Guiding Principles for scientific data management and stewardship](https://doi.org/10.1038/sdata.2016.18). *Scientific Data*, 3, 160018. (G20, EU, NIH endorsement)
  1516. - W3C (2013). [PROV-DM: The PROV Data Model](https://www.w3.org/TR/prov-dm/). W3C Recommendation.
  1517. - CCSDS (2024). [Reference Model for an Open Archival Information System (OAIS)](https://public.ccsds.org/Pubs/650x0m2.pdf). ISO 14721. (Digital preservation lifecycle)
  1518. - GRADE Working Group (2004–present). [GRADE Handbook](https://www.gradeworkinggroup.org/). Evidence quality assessment. Adopted by WHO, Cochrane, NICE, and 100+ organizations.
  1519. - Schmidgall, S. et al. (2025). [Agent Laboratory: Using LLM Agents as Research Assistants](https://arxiv.org/abs/2501.04227).
  1520. - Sureshkumar, V. et al. (2026). [R-LAM: Towards Reproducibility in Large Action Model Workflows](https://arxiv.org/abs/2601.09749).
  1521. - ServiceNow Research (2025). LitLLM for Scientific Literature Reviews. RAG-based literature review, no hallucination approach.
  1522. ### AI Safety & Failure Modes
  1523. - Tang, R. et al. (2023). [Large Language Models Can be Lazy Learners: Analyze Shortcuts in In-Context Learning](https://arxiv.org/abs/2305.17256). *ACL 2023 Findings*. doi:10.18653/v1/2023.findings-acl.284
  1524. - Bandara, E. et al. (2025). [A Practical Guide for Designing, Developing, and Deploying Production-Grade Agentic AI Workflows](https://arxiv.org/abs/2512.08769).
  1525. - Roig, J.V. (2025). [How Do LLMs Fail In Agentic Scenarios? A Qualitative Analysis](https://arxiv.org/abs/2512.07497).
  1526. - Von Arx, S., Chan, L. & Barnes, E. (2025). [Recent Frontier Models Are Reward Hacking](https://metr.org/blog/2025-06-05-recent-reward-hacking/). METR Research Blog.
  1527. - Anthropic Alignment Team (2025). [From shortcuts to sabotage: Natural emergent misalignment from reward hacking](https://www.anthropic.com/research/emergent-misalignment-reward-hacking). Anthropic Research.
  1528. - Batista, R.M. & Griffiths, T.L. (2026). [A Rational Analysis of the Effects of Sycophantic AI](https://arxiv.org/abs/2602.14270). (Bayesian analysis, epistemic risk)
  1529. - Kumar, R.S.S. et al. (2025). [Taxonomy of Failure Modes in Agentic AI Systems](https://www.microsoft.com/en-us/security/blog/2025/04/24/new-whitepaper-outlines-the-taxonomy-of-failure-modes-in-ai-agents/). Microsoft Security.
  1530. - Twiss, J. (2026). [AI Coding Degrades: Silent Failures Emerge](https://spectrum.ieee.org/ai-coding-degrades). *IEEE Spectrum*.
  1531. - van Linschoten, A.S. (2025). [The Agent Deployment Gap: Why Your LLM Loop Isn't Production-Ready](https://www.zenml.io/blog/the-agent-deployment-gap-why-your-llm-loop-isnt-production-ready-and-what-to-do-about-it). ZenML.
  1532. ### Task Decomposition & Declarative Pipelines
  1533. - Khot, T. et al. (2023). [Decomposed Prompting: A Modular Approach for Solving Complex Tasks](https://arxiv.org/abs/2210.11610). *ICLR 2023*.
  1534. - Khattab, O. et al. (2023). [DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines](https://arxiv.org/abs/2310.03714). *ICLR 2024*.
  1535. - Dohan, D. et al. (2022). [Language Model Cascades](https://arxiv.org/abs/2207.10342). Google Brain. (PGM formalization of multi-step LLM pipelines)

Lines 2,001–2,347 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.