diff --git a/AGENTS.md b/AGENTS.md index 91852b5..3329fcb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,9 @@ # Agent Plugins contributor guide -This repository owns reusable plugin content under `plugins/`. The AllAgents CLI, client adapters and workspace examples belong in `allagentsdev/allagents`. +This repository owns reusable plugin content under `plugins/` and workspace templates under the sibling `workspaces/` directory. The AllAgents CLI, client adapters and CLI-specific examples belong in `allagentsdev/allagents`. - Work on a dedicated branch/worktree from current `origin/main`; publish changes through a pull request. Never push implementation directly to `main` or merge without user authorization. Use conventional commit and PR titles; squash merges. +- Keep workspace recipes portable. Use original upstream skill sources, preserve copied recipes' behavior, and document software/account prerequisites separately from skill installation. - Keep `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json` aligned for the complete catalogue. Both use the marketplace name `agent-plugins` and local paths to plugin directories. - Preserve plugin names, licensing, attribution, executable file modes and supporting resources. Update plugin homepages and local links when moving files. - Keep skills scoped to reusable capabilities. Keep household data, private service configuration, credentials and downloaded personal workbooks in their private repositories. diff --git a/README.md b/README.md index 087c5aa..7e003d6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Agent Plugins -Reusable plugins for AI assistants, maintained by AllAgents. This repository is the plugin catalogue; the [AllAgents CLI and workspace examples](https://github.com/allagentsdev/allagents) remain in their own repository. +Reusable plugins for AI assistants, maintained by AllAgents. This repository owns the plugin catalogue and [workspace templates](workspaces). The [AllAgents CLI and client adapters](https://github.com/allagentsdev/allagents) remain in their own repository. ## Install @@ -46,14 +46,25 @@ Save personal selections and private reports in `~/.agents/github-attention.md`, ## Workspace templates -Workspace templates remain under [allagents/examples/workspaces](https://github.com/allagentsdev/allagents/tree/main/examples/workspaces). They compose plugins from this catalogue and other sources: +[Workspace templates](workspaces) live beside `plugins/` and compose this +catalogue with original upstream sources: -```yaml -plugins: - - finance@allagentsdev/agent-plugins - - engineering@allagentsdev/agent-plugins +| Template | Purpose | +| --- | --- | +| [Designer](workspaces/designer) | Interfaces, film, video editing, motion, audio review and marketing | +| [Engineering](workspaces/engineering) | Portable engineering skills and Pi-native tooling | +| [Finance](workspaces/finance) | Financial models, budgets, forecasts and workpapers | + +```sh +allagents workspace init ./designer \ + --from allagentsdev/agent-plugins/workspaces/designer ``` +Read each template's prerequisites first. Skill installation is separate from +media software, service authentication and paid generation. Engineering and +Finance were copied from the AllAgents examples; CLI-specific examples remain +in that repository. + The companion AllAgents migration preserves the old marketplace declarations, such as `finance@allagentsdev/allagents`, through external sources. Direct old directory URLs for the moved plugins do not redirect: replace `allagentsdev/allagents/plugins/` with `@allagentsdev/agent-plugins`. Upgrade AllAgents before using the migrated forwarding marketplace. Pinned historical versions continue to use their original content. ## Development diff --git a/workspaces/README.md b/workspaces/README.md new file mode 100644 index 0000000..b16c747 --- /dev/null +++ b/workspaces/README.md @@ -0,0 +1,30 @@ +# Workspace templates + +These recipes compose plugins and original upstream skills into a project +workspace. Reusable plugins and workspace compositions live together in this +repository; the CLI and client adapters live in +[allagentsdev/allagents](https://github.com/allagentsdev/allagents). + +| Workspace | Purpose | +| --- | --- | +| [Designer](designer) | Interfaces, film, editing, motion, audio review and marketing | +| [Engineering](engineering) | Portable engineering skills and Pi-native tools | +| [Finance](finance) | Financial modeling, budgets, forecasts and workpapers | + +Use the template's README for prerequisites and account setup. For example: + +```sh +allagents workspace init ./designer \ + --from allagentsdev/agent-plugins/workspaces/designer +``` + +Engineering and Finance were copied from the AllAgents +[engineering](https://github.com/allagentsdev/allagents/tree/782ffc9/examples/workspaces/engineering) +and [finance](https://github.com/allagentsdev/allagents/tree/782ffc9/examples/workspaces/finance) +examples. Their workspace declarations are unchanged; their documentation points +to the copies maintained here. The CLI repository's existing examples remain +available for users of those earlier URLs. + +Templates describe dependencies; they do not grant credentials, provider access +or permission to spend money. Engineering includes Pi-native packages and +explicit setup commands: read its trust and installation instructions first. diff --git a/workspaces/designer/.allagents/workspace.yaml b/workspaces/designer/.allagents/workspace.yaml new file mode 100644 index 0000000..b8ba51e --- /dev/null +++ b/workspaces/designer/.allagents/workspace.yaml @@ -0,0 +1,44 @@ +version: 2 + +repositories: + - path: . + description: Design project, source assets and editable deliverables + skills: false + # Keep Video Use's root skill and helpers in their original repository. + # Plugin discovery otherwise selects its nested Manim skill instead. + - path: sources/video-use + source: github + repo: browser-use/video-use + managed: clone + ref: main + description: Read-only upstream Video Use reference and video-editing helpers + skills: false + +plugins: + - source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/main/.claude + install: file + - source: https://github.com/remotion-dev/skills + install: file + - source: https://github.com/LottieFiles/motion-design-skill + install: file + - source: https://github.com/wuwangzhang1216/DirectorSKILL + install: file + - source: https://github.com/NousResearch/hermes-agent/tree/main/skills/creative/songwriting-and-ai-music + install: file + skills: [songwriting-and-ai-music] + - source: https://github.com/coreyhaines31/marketingskills + install: file + skills: [product-marketing, content-strategy, copywriting, ad-creative] + - source: https://github.com/JimLiu/baoyu-skills + install: file + skills: [baoyu-infographic, baoyu-comic] + - source: https://github.com/Leonxlnx/earshot + install: file + skills: [earshot] + - source: https://github.com/greensock/gsap-skills + install: file + skills: [gsap-core, gsap-timeline, gsap-scrolltrigger, gsap-react] + - productivity@allagentsdev/agent-plugins + +clients: + - universal diff --git a/workspaces/designer/AGENTS.md b/workspaces/designer/AGENTS.md new file mode 100644 index 0000000..5a49f3b --- /dev/null +++ b/workspaces/designer/AGENTS.md @@ -0,0 +1,45 @@ +# Designer + +Design interfaces, direct films, edit recorded videos and develop marketing +creative. Keep editable sources and inspect the rendered result. Apply the +installed `write-naturally` skill to user-facing writing. + +Read the project's brief, design system and references first. Choose one design +lead and the few specialist skills needed for the task. Read a skill before +using its scripts or following its production workflow. + +| Work | Skill or source | +| --- | --- | +| Interfaces and design systems | `ui-ux-pro-max` | +| Story, shots, blocking and continuity | `cinematic-director` | +| Video composition and rendering | `remotion-best-practices` and its relevant specialist skill | +| Tutorial editing, retakes, captions and cut decisions | Read `sources/video-use/SKILL.md`; use its original helpers with FFmpeg | +| Timing, staging and choreography | `motion-design` | +| Interactive browser animation | `gsap-core`, `gsap-timeline`, `gsap-scrolltrigger`; `gsap-react` in React | +| Audio measurement and event analysis | `earshot` | +| Lyrics, song structure and music prompts | `songwriting-and-ai-music` | +| Positioning, campaigns and copy | `product-marketing`, `content-strategy`, `copywriting`, `ad-creative` | +| Illustrated explainers | `baoyu-infographic` or `baoyu-comic`, when requested | + +The project root holds working material and deliverables. Treat +`sources/video-use/` as an unchanged upstream reference. Read its root skill +directly; AllAgents' plugin discovery would prefer the nested Manim skill. +Preserve source footage and keep narration, music, effects and captions editable. +Review cuts against picture and speech; silence alone is not a reason to cut. +Recalculate captions and chapters on the edited timeline. + +For 3D work, use Blender and its original MCP bridge when installed. Start it +only for the active task and keep the bridge on loopback. In Remotion, derive +animation from the composition frame or seek a paused GSAP timeline so rendering +is deterministic. Inspect desktop/mobile layouts, keyboard interaction and +reduced-motion behavior for interface work. + +Skills provide guidance; verify local tools and service authentication before +using them. Load credentials inside the API client from private runtime storage +or the owner's credential manager. Keep them out of chat, project `.env` files +and Git. This overrides upstream examples asking for pasted keys. Paid media +generation, transcription, public uploads and posting require explicit owner +authorization. Earshot's optional audio-LLM upload also needs consent. + +Finish with editable sources, requested exports, checks performed and any +remaining limitations. Keep caches and large generated media outside Git. diff --git a/workspaces/designer/README.md b/workspaces/designer/README.md new file mode 100644 index 0000000..97106c0 --- /dev/null +++ b/workspaces/designer/README.md @@ -0,0 +1,86 @@ +# Designer workspace + +A project workspace for interface design, film direction, video editing, motion, +audio review and marketing creative. It composes original publisher skills and +keeps the Video Use editing skill with its upstream helpers. + +## Create a workspace + +```sh +allagents workspace init ./designer \ + --from allagentsdev/agent-plugins/workspaces/designer +cd designer +printf '\n/sources/video-use/\n' >> .gitignore +allagents plugin list +``` + +Use AllAgents 1.23.0 or newer, Git and network access. The default `universal` +client installs portable skills into `.agents/skills/`. Clients such as Codex +and Pi can discover that directory. Select other clients with `--client` during +initialization when their own resource directories are needed. + +The ignore entry keeps the upstream reference checkout outside project commits. +It appends to an existing `.gitignore`. + +The template copies its [Designer guidance](AGENTS.md) into new workspaces while +preserving an existing `AGENTS.md`. In an existing project, incorporate the +relevant guidance into that file yourself. Installation does not start an agent +or create a separate authenticated bot. + +## Skill stack + +| Source | Purpose | +| --- | --- | +| [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | Interface and design-system lead | +| [Remotion](https://github.com/remotion-dev/skills) | Composition, titles, overlays and rendering | +| [Motion Design](https://github.com/LottieFiles/motion-design-skill) | Timing, easing, staging and choreography | +| [DirectorSKILL](https://github.com/wuwangzhang1216/DirectorSKILL) | Story, shot coverage, blocking and continuity | +| [Video Use](https://github.com/browser-use/video-use) | Recorded footage, tutorial editing, transcripts and cut decisions | +| [Hermes songwriting](https://github.com/NousResearch/hermes-agent/tree/main/skills/creative/songwriting-and-ai-music) | Lyrics, song structure and music prompts | +| [Corey Haines marketing skills](https://github.com/coreyhaines31/marketingskills) | Four selected positioning, content, copy and ad skills | +| [Baoyu skills](https://github.com/JimLiu/baoyu-skills) | Infographics and comics | +| [Earshot](https://github.com/Leonxlnx/earshot) | Local audio measurements and model-assisted review | +| [Official GSAP skills](https://github.com/greensock/gsap-skills) | Core, timelines, ScrollTrigger and React | +| [Productivity](../../plugins/productivity) | Write Naturally | + +Video Use has a root editing skill and a nested Manim skill. AllAgents' plugin +discovery prefers the nested directory, so this recipe instead clones the +original repository to `sources/video-use/` and points the agent to its root +`SKILL.md`. Its skill and helper bytes stay unchanged. The reference uses +`managed: clone`: AllAgents creates it when missing and does not pull it during +later updates. Review upstream changes before updating that checkout. Keep the +reference checkout and render caches out of your project's Git history. + +## Software and accounts + +Workspace initialization installs instructions and the Video Use reference. It +does not install media binaries, download audio models, authenticate services or +generate paid content. + +| Primitive | Separate setup | +| --- | --- | +| FFmpeg and ffprobe | Install through your operating-system package manager | +| Remotion | Install Node.js and the project's Remotion/React packages; prepare its browser renderer | +| Video Use | Install Python and its declared dependencies; transcription needs ElevenLabs API access | +| GSAP | Install `gsap` and, for React projects, `@gsap/react` in the project | +| Earshot | Install the original CLI/MCP package and download its CLAP/AST models; analysis runs locally on CPU | +| Blender | Install Blender and the [original MCP bridge](https://github.com/ahujasid/mcp-for-blender) if needed; its bridge uses a normal Blender session and can run under Xvfb on Linux | +| Generated footage, music and voice | Configure Higgsfield, Suno and ElevenLabs separately through their official APIs or supported authenticated tools | + +Earshot and the Blender bridge currently require different major versions of +Python's MCP package; use separate environments. GSAP requires no AI model. +Earshot's Gemini critique is optional and uploads audio only with consent. +For ElevenLabs API-key use, prefer its maintained official SDK; hosted MCP OAuth +is a separate connection. Keep credentials in private runtime storage and load +them inside the client process. Setup does not authorize paid generation, +transcription or publishing. + +## Update + +```sh +allagents update +``` + +This reconciles the declared plugin sources. It does not pull the Video Use +reference or install/update your project's media dependencies. Restart the agent +after skill changes and verify rendered output in the production toolchain. diff --git a/workspaces/engineering/.allagents/workspace.yaml b/workspaces/engineering/.allagents/workspace.yaml new file mode 100644 index 0000000..ab4f110 --- /dev/null +++ b/workspaces/engineering/.allagents/workspace.yaml @@ -0,0 +1,57 @@ +version: 2 + +setup: + - run: curl -fsSL https://herdr.dev/install.sh | sh + platforms: [linux, darwin] + - run: 'powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"' + platforms: [win32] + +repositories: [] + +plugins: + # Enable the complete Compound Engineering plugin from its default branch. + - source: https://github.com/EveryInc/compound-engineering-plugin + + # Preserve Matt's upstream composition by installing the selected capabilities + # with every helper skill they invoke. The explicit closure prevents unrelated + # additions from auto-enabling while keeping each selected workflow complete. + - source: https://github.com/mattpocock/skills + skills: + - engineering/wayfinder + - engineering/grill-with-docs + - engineering/improve-codebase-architecture + - engineering/domain-modeling + - engineering/research + - engineering/prototype + - engineering/codebase-design + - engineering/setup-matt-pocock-skills + - productivity/grilling + + - source: https://github.com/NousResearch/hermes-agent + skills: + - research/llm-wiki + + - source: https://github.com/herdrdev/herdr + skills: + - herdr + + # Pi owns package installation and loading. Explicit client overrides keep + # these packages separate from the universal file-mode skills above. + # Save project trust and select native CE skills in Pi before initialization; + # see ../README.md. Portable CE files otherwise shadow the native skills. + # npm packages retain reviewed pins; Compound Engineering follows upstream. + - source: npm:pi-web-access@0.37.0 + clients: [pi] + install: native + - source: git:github.com/EveryInc/compound-engineering-plugin + clients: [pi] + install: native + - source: npm:pi-subagents@0.76.1 + clients: [pi] + install: native + - source: npm:pi-ask-user@0.16.0 + clients: [pi] + install: native + +clients: + - universal diff --git a/workspaces/engineering/README.md b/workspaces/engineering/README.md new file mode 100644 index 0000000..1e07c33 --- /dev/null +++ b/workspaces/engineering/README.md @@ -0,0 +1,154 @@ +# Engineering + +One project workspace with portable engineering skills and Pi-native tools. +The portable sources install into `.agents/skills/` through the `universal` +client: Compound Engineering, selected Matt Pocock workflows and their helpers, +Hermes LLM Wiki, and Herdr. The workspace also retains the optional Herdr +installation commands, which run only when you invoke `allagents workspace setup`. + +The following packages install through Pi's native lifecycle: + +| Package | Purpose | +| --- | --- | +| [pi-web-access](https://github.com/nicobailon/pi-web-access) | Web research and source retrieval | +| [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin#pi) | Official upstream Pi package: brainstorm, plan, implement, review, and capture lessons | +| [pi-subagents](https://github.com/nicobailon/pi-subagents) | Delegation and parallel agent work | +| [pi-ask-user](https://github.com/edlsh/pi-ask-user) | Structured clarification and interactive decisions | + +Pi Compound Engineering uses subagents and interactive questions in its workflows; +web access supplies the research tools. Each native declaration targets only `pi` +with `install: native`, while the portable sources inherit `universal` file +installation. The two Compound Engineering distributions remain separate +resources with independent destinations and lifecycles. Both follow the upstream +default branch; Pi installs the upstream Git package directly. The npm packages +remain pinned to reviewed versions. + +## Prerequisites + +- Pi on `PATH`; this stack is verified with Pi **1.1.0**. AllAgents must + include the minimum-only Pi compatibility fix (older AllAgents versions reject + Pi releases after 0.85.x). +- Node.js **22.19.0 or newer**, npm, Git, and network access during installation. +- Review the third-party packages before trusting the project. Pi extensions and + package lifecycle scripts execute code with your user account's permissions. + +## Create a workspace + +Save trust for the actual target directory **before** AllAgents attempts native +installation: + +```sh +mkdir engineering-demo +cd engineering-demo +pi +``` + +In Pi, run `/trust`, save a trusted decision for this folder, then exit. A one-time +`--approve` is not a saved decision and does not authorize AllAgents' later +processes. AllAgents reads trust from the user Pi agent root outside the project; +it does not set `defaultProjectTrust: always` or grant trust through setup scripts. + +Pi automatically discovers `.agents/skills` before package skills. Without a +resource selection, the portable Compound Engineering skills shadow the native +Pi versions. From this project directory, append exclusions for the portable +Compound Engineering files to your existing `.pi/settings.json`: + +```sh +node --input-type=module <<'JS' +import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +const path = resolve('.pi/settings.json'); +const settings = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : {}; +if (settings.skills !== undefined && !Array.isArray(settings.skills)) { + throw new Error('Expected settings.skills to be an array; no settings were changed.'); +} +const portable = resolve('.agents/skills').replaceAll('\\', '/'); +settings.skills = [...new Set([ + ...(settings.skills ?? []), + `!${portable}/ce-*/SKILL.md`, + `!${portable}/lfg/SKILL.md`, +])]; +mkdirSync('.pi', { recursive: true }); +writeFileSync(path, JSON.stringify(settings, null, 2) + '\n'); +JS +``` + +This preserves existing settings and skill selections. Pi still loads the other +universal skills and custom `.pi/skills` resources, while Compound Engineering +comes from the native package. The exclusions use the actual project path so +they also work beneath hidden directories. These machine-specific selections +remain user-owned; keep them out of the shared template and rerun the command if +you move the project. AllAgents preserves them when installing or updating packages. + +Then initialize and install the stack: + +```sh +allagents workspace init . \ + --from allagentsdev/agent-plugins/workspaces/engineering +allagents plugin list +pi list +pi +``` + +From a local repository checkout, replace `--from` with the absolute path to +`workspaces/engineering`. + +In the new Pi session, inspect `/subagents-doctor` and the `/skill:ce-` command +completions. Confirm the Compound Engineering skills are listed and the question +and web tools are available; some tools activate on demand. Installing packages +alone does not verify provider credentials or execute delegated work. + +## Ownership and configuration + +The template declares packages under `plugins` with `clients: [pi]` and +`install: native`. AllAgents invokes +Pi's native lifecycle rather than copying TypeScript extensions or running a +second install script. Pi writes project package declarations to +`.pi/settings.json`, installs npm packages under `.pi/npm/`, and checks out Git +packages under `.pi/git/`. AllAgents tracks +its native resources in `.allagents/sync-state.json` and preserves pre-existing, +referenced installations when removing declarations. + +Your Pi model authentication and web-provider configuration remain user-owned. +Configure Pi authentication normally. Web access supports keyless search and can +reuse supported Pi authentication; consult its upstream README for provider +selection and optional `~/.pi/agent/web-search.json` configuration. Keep API keys, +OAuth state, and machine-specific settings out of the shared template. + +The official Compound Engineering Git package includes its skills in the repository +and loads them through Pi's native package manifest. It does not use the former +`pi-compound-engineering` adaptation's skill-generation scripts or `/ce-status` +command. After installing or updating the package, run `/reload` or restart Pi. + +## Update or remove + +The recipe pins reviewed npm package versions. To upgrade an npm package, change +its pin in `.allagents/workspace.yaml`, review that release, then run a targeted update: + +```sh +allagents plugin update npm:pi-web-access --scope project +``` + +Updating an npm package without changing its pin reconciles the pinned version; +it does not select latest. Compound Engineering has no pinned ref in either +declaration. Run `allagents plugin update --scope project` to fetch its latest +default-branch revision for both the portable files and the Pi-native package. + +When migrating an existing workspace from `npm:pi-compound-engineering@3.19.2`, +run `allagents plugin uninstall npm:pi-compound-engineering --scope project` before +replacing its declaration with the upstream Git package. This lets AllAgents +reconcile the old managed installation. Check `pi list` for a separately installed +user package and remove that old adaptation in Pi if present; loading both CE +packages can leave duplicate skill names. + +To remove a declaration and safely reconcile its managed installation: + +```sh +allagents plugin uninstall npm:pi-web-access --scope project +``` + +If the same package is also configured globally, AllAgents refuses a targeted +update that could affect both scopes. Avoid duplicating this stack globally and +project-locally. For a personal stack shared across unrelated projects, use an +[AllAgents global profile](https://allagents.dev/docs/reference/configuration/#global-profiles) +instead of this project template. diff --git a/workspaces/finance/.allagents/workspace.yaml b/workspaces/finance/.allagents/workspace.yaml new file mode 100644 index 0000000..583f1ba --- /dev/null +++ b/workspaces/finance/.allagents/workspace.yaml @@ -0,0 +1,9 @@ +version: 2 + +repositories: [] + +plugins: + - finance@allagentsdev/agent-plugins + +clients: + - universal diff --git a/workspaces/finance/README.md b/workspaces/finance/README.md new file mode 100644 index 0000000..5b6216a --- /dev/null +++ b/workspaces/finance/README.md @@ -0,0 +1,12 @@ +# Finance workspace + +A portable workspace for financial modeling, budgets, forecasts and workpapers. +It installs the reusable Finance plugin from `allagentsdev/agent-plugins`. + +```sh +allagents workspace init ./finance --from allagentsdev/agent-plugins/workspaces/finance +cd finance +allagents update +``` + +Review model inputs, formulas and checks before using financial outputs.