From 43fb078de397ede3321370907b93950795d1fd61 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 29 Aug 2026 18:13:19 +0000 Subject: [PATCH 1/4] Expand agent skill stack with tiered install and selective S-tier additions - Add CORE/EXTENDED/OPTIONAL tiers via BERD_SKILLS_TIER - Pin skills CLI version from skills-lock.json (skillsCli: 1.5.23) - Add hallmark, deep-research, last30days to EXTENDED tier - Add Context7 MCP to .cursor/mcp.json - Document conflict warnings, optional tools (OpenSpec, Graphify, Impeccable) Co-authored-by: Prax Lannister --- .agents/skills/README.md | 67 ++++++++++++++- .cursor/mcp.json | 8 ++ AGENTS.md | 13 ++- scripts/install-agent-skills.sh | 139 +++++++++++++++++++++++--------- skills-lock.json | 1 + 5 files changed, 188 insertions(+), 40 deletions(-) create mode 100644 .cursor/mcp.json diff --git a/.agents/skills/README.md b/.agents/skills/README.md index adb3a5465..2a5e1b236 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -39,15 +39,51 @@ discover → interrogate/spec → plan → implement → review → security → Also installed: **Anthropic dev subset** (MCP builder, frontend-design, webapp-testing, etc.) and **awesome-copilot** (417-skill toolbox). +## Install tiers + +The install script supports three tiers via `BERD_SKILLS_TIER`: + +| Tier | Env value | What installs | +| --- | --- | --- | +| **CORE** (default) | `core` | Layered pipeline packs (~740 skills) | +| **EXTENDED** | `extended` | CORE + selective S-tier additions below | +| **ALL** | `all` | EXTENDED + optional hooks (no bulk verticals) | + +```bash +./scripts/install-agent-skills.sh # CORE (default) +BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh +``` + +The script pins `npx skills` to the version in `skills-lock.json` (`skillsCli` field). Override with `SKILLS_CLI_VERSION=latest` if needed. + +## Extended tier additions + +| Skill | Source | Role | +| --- | --- | --- | +| **hallmark** | [nutlope/hallmark](https://github.com/nutlope/hallmark) | UI taste gate — anti-AI-slop design for greenfield pages and redesigns | +| **deep-research** | [24601/agent-deep-research](https://github.com/24601/agent-deep-research) | Async deep research (one skill, not four parallel systems) | +| **last30days** | [mvanhorn/last30days-skill](https://github.com/mvanhorn/last30days-skill) | Recency radar — what people say about a topic in the last 30 days | + +## Conflict warnings + +Do **not** run multiple full methodologies on the same task — pick one primary workflow: + +| Task type | Pick one | Avoid stacking | +| --- | --- | --- | +| Planning | pstack `/poteto-mode` **or** superpowers `/writing-plans` **or** gstack `/plan-ceo-review` | All three in one session | +| Code review | Berd `code-review` **or** compound `ce-code-review` **or** mattpocock `/code-review` | Redundant review passes | +| UI design | hallmark **or** shadcn `/improve` design sections | Duplicate design audits | +| Research | `deep-research` **or** `last30days` **or** compound research agents | Four parallel research systems | + ## Install or refresh ```bash ./scripts/install-agent-skills.sh ``` -The script uses [`npx skills@latest`](https://github.com/vercel-labs/skills) with `-a cursor -y --copy` (Cursor only, project-local). It restores Berd-owned skills after upstream packs are copied and removes junk agent directories. +The script uses [`npx skills`](https://github.com/vercel-labs/skills) (pinned via `skills-lock.json`) with `-a cursor -y --copy` (Cursor only, project-local). It restores Berd-owned skills after upstream packs are copied and removes junk agent directories. -Run twice to verify idempotence. Expect ~740 skills after a full install. +Run twice to verify idempotence. Expect ~740 skills after CORE; ~743 after EXTENDED. ## One-time repo setup @@ -156,13 +192,40 @@ Install manually when relevant: npx skills@latest add supabase/agent-skills --skill '*' -a cursor -y --copy npx skills@latest add cloudflare/skills --skill '*' -a cursor -y --copy npx skills@latest add aws/agent-toolkit-for-aws/skills --skill '*' -a cursor -y --copy +# Remotion vertical (12 skills — install one, not all): +npx skills@latest add remotion-dev/skills --skill remotion-best-practices -a cursor -y --copy +# NVIDIA (343 skills — pick individual skills only): +npx skills@latest add nvidia/skills --list +npx skills@latest add nvidia/skills --skill -a cursor -y --copy ``` +## MCP servers + +Project MCP config: `.cursor/mcp.json` + +| Server | Command | Purpose | +| --- | --- | --- | +| **Context7** | `npx -y @upstash/context7-mcp` | Up-to-date library documentation lookup | + +## Optional runtime tools (manual) + +These are **not** run by the install script. Install when needed: + +| Tool | Install | Notes | +| --- | --- | --- | +| **OpenSpec** | `npm install -g @fission-ai/openspec@latest` then `openspec init` | Creates `openspec/` structure for spec-driven workflows | +| **Graphify** | `uv tool install graphifyy` then `graphify cursor install --project` | Requires `uv` on PATH; visualizes codebase graphs | +| **Impeccable** | `npx impeccable skills install` (project) then `/impeccable init` in Agent chat | Design-system skill; installs to `.cursor/` and `.agents/` | +| **agent-browser CLI** | `npm install -g agent-browser` | Required for browser QA layer (see above) | + ## Searchable armory (do NOT bulk-install) | Pack | Source | Notes | | --- | --- | --- | | **Microsoft skills** | [microsoft/skills](https://github.com/microsoft/skills) | Large repo — context rot risk. Use `npx skills add microsoft/skills --list` and install individual skills only. | +| **wshobson/agents** | [wshobson/agents](https://github.com/wshobson/agents) | 94 plugins — do NOT bulk install | +| **NVIDIA skills** | [nvidia/skills](https://github.com/nvidia/skills) | 343 GPU/AI-Q skills — install individual skills only | +| **everything-claude-code** | various | Redundant with gstack + superpowers + pstack + compound — skip | | Vercel skills CLI | [vercel-labs/skills](https://github.com/vercel-labs/skills) | Package manager for all skills | | Anthropic skills | [anthropics/skills](https://github.com/anthropics/skills) | Dev subset installed; browse for more | | Supabase | [supabase/agent-skills](https://github.com/supabase/agent-skills) | Postgres/Supabase workflows | diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 000000000..d8981ab2f --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} diff --git a/AGENTS.md b/AGENTS.md index bba2d64e8..ef94d5334 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,7 +126,18 @@ local override. ## Agent skills -Project skills live in `.agents/skills/`. Install or refresh with `./scripts/install-agent-skills.sh`. **gstack** (`/plan-ceo-review`, `/ship`, `/qa`, …) also needs its runtime: `./scripts/install-gstack-runtime.sh` (runs automatically at the end of the skill install script). See `.agents/skills/README.md`. +Project skills live in `.agents/skills/`. Install or refresh: + +```bash +./scripts/install-agent-skills.sh # CORE tier (default) +BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh # + hallmark, deep-research, last30days +``` + +**gstack** (`/plan-ceo-review`, `/ship`, `/qa`, …) also needs its runtime: `./scripts/install-gstack-runtime.sh` (runs automatically at the end of the skill install script). + +- Stack tiers, conflict warnings, and optional tools: `.agents/skills/README.md` +- MCP servers (Context7): `.cursor/mcp.json` +- Skills CLI version pin: `skills-lock.json` → `skillsCli` ### Issue tracker diff --git a/scripts/install-agent-skills.sh b/scripts/install-agent-skills.sh index 55fd20d90..6730019c2 100755 --- a/scripts/install-agent-skills.sh +++ b/scripts/install-agent-skills.sh @@ -4,6 +4,28 @@ set -euo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" cd "$repo_root" +# Tier: core (default) | extended | all +# core — layered pipeline packs (default Berd stack) +# extended — core + selective S-tier additions (hallmark, deep-research, last30days) +# all — extended + optional verticals (none bulk-installed by default) +readonly BERD_SKILLS_TIER="${BERD_SKILLS_TIER:-core}" + +# Pin skills CLI when skills-lock.json records a version (falls back to latest). +skills_cli_version() { + if [[ -f "$repo_root/skills-lock.json" ]] && command -v jq >/dev/null 2>&1; then + local pinned + pinned="$(jq -r '.skillsCli // empty' "$repo_root/skills-lock.json" 2>/dev/null || true)" + if [[ -n "$pinned" ]]; then + echo "$pinned" + return + fi + fi + echo "latest" +} + +readonly SKILLS_CLI="$(skills_cli_version)" +readonly SKILLS_NPX=(npx --yes "skills@${SKILLS_CLI}") + # Berd-owned skills that must not be overwritten by upstream packs. readonly -a PROTECTED_SKILLS=( assistive-ux @@ -48,14 +70,82 @@ remove_gstack_fixtures() { install_pack() { local spec="$1" shift - npx --yes skills@latest add "$spec" --skill '*' -a cursor -y --copy "$@" + "${SKILLS_NPX[@]}" add "$spec" --skill '*' -a cursor -y --copy "$@" } # Install one or more named skills from a pack. install_skills() { local spec="$1" shift - npx --yes skills@latest add "$spec" -a cursor -y --copy "$@" + "${SKILLS_NPX[@]}" add "$spec" -a cursor -y --copy "$@" +} + +tier_at_least() { + local want="$1" + case "$BERD_SKILLS_TIER" in + core) [[ "$want" == "core" ]] ;; + extended) [[ "$want" == "core" || "$want" == "extended" ]] ;; + all) true ;; + *) + echo "error: unknown BERD_SKILLS_TIER=$BERD_SKILLS_TIER (use core|extended|all)" >&2 + exit 1 + ;; + esac +} + +# ── CORE tier ──────────────────────────────────────────────────────────────── +# Layer: discover → interrogate/spec → plan → implement → review → security → browser QA → ship → learn +install_core_tier() { + echo "Installing CORE tier (skills@${SKILLS_CLI}) …" + + install_pack shadcn/improve + install_pack obra/superpowers + install_pack mattpocock/skills --full-depth + install_pack garrytan/gstack + install_pack cursor/plugins --full-depth + install_pack vercel-labs/agent-skills + + install_pack trailofbits/skills + + install_skills vercel-labs/skills --skill find-skills + install_skills vercel-labs/agent-browser --skill agent-browser + + install_skills anthropics/skills \ + --skill claude-api \ + --skill doc-coauthoring \ + --skill frontend-design \ + --skill mcp-builder \ + --skill skill-creator \ + --skill web-artifacts-builder \ + --skill webapp-testing + + install_pack github/awesome-copilot + + if ! install_pack EveryInc/compound-engineering-plugin 2>/dev/null; then + echo "Note: EveryInc/compound-engineering-plugin install failed; use /add-plugin compound-engineering in Cursor." + fi +} + +# ── EXTENDED tier ──────────────────────────────────────────────────────────── +# Selective S-tier additions — one skill per pack, project-local only. +install_extended_tier() { + echo "Installing EXTENDED tier …" + + install_skills nutlope/hallmark --skill hallmark + install_skills 24601/agent-deep-research --skill deep-research + install_skills mvanhorn/last30days-skill --skill last30days +} + +# ── OPTIONAL tier ──────────────────────────────────────────────────────────── +# Documented verticals — install individually, never bulk (context rot). +# Uncomment or run manually when relevant: +# +# install_skills remotion-dev/skills --skill remotion-best-practices +# install_skills nvidia/skills --skill # 343 skills — pick one +# npx skills add microsoft/skills --list # armory only +# npx skills add wshobson/agents --list # 94 plugins — do NOT bulk install +install_optional_tier() { + echo "OPTIONAL tier: no bulk installs (see .agents/skills/README.md)." } # Optional packs — install manually when relevant (not part of default stack): @@ -66,43 +156,18 @@ install_skills() { # npx skills@latest add microsoft/skills --list # npx skills@latest add microsoft/skills --skill -a cursor -y --copy -echo "Installing agent skill packs into .agents/skills/ …" +echo "BERD_SKILLS_TIER=$BERD_SKILLS_TIER" -# Layer: discover → interrogate/spec → plan → implement → review → security → browser QA → ship → learn +if tier_at_least core; then + install_core_tier +fi + +if tier_at_least extended; then + install_extended_tier +fi -# Core workflow packs -install_pack shadcn/improve -install_pack obra/superpowers -install_pack mattpocock/skills --full-depth -install_pack garrytan/gstack -install_pack cursor/plugins --full-depth -install_pack vercel-labs/agent-skills - -# Security layer -install_pack trailofbits/skills - -# Discovery -install_skills vercel-labs/skills --skill find-skills - -# Browser QA -install_skills vercel-labs/agent-browser --skill agent-browser - -# Anthropic dev/engineering subset (skip pure creative/doc examples) -install_skills anthropics/skills \ - --skill claude-api \ - --skill doc-coauthoring \ - --skill frontend-design \ - --skill mcp-builder \ - --skill skill-creator \ - --skill web-artifacts-builder \ - --skill webapp-testing - -# Toolbox -install_pack github/awesome-copilot - -# Compound engineering (learn layer) — plugin install fallback documented in README -if ! install_pack EveryInc/compound-engineering-plugin 2>/dev/null; then - echo "Note: EveryInc/compound-engineering-plugin install failed; use /add-plugin compound-engineering in Cursor." +if tier_at_least all; then + install_optional_tier fi restore_protected_skills diff --git a/skills-lock.json b/skills-lock.json index a311f72e7..dab9665ff 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -1,5 +1,6 @@ { "version": 1, + "skillsCli": "1.5.23", "skills": { "Make Bot UI": { "source": "cursor/plugins", From 9aa9cc96dbca037af8726ffa41cffea70c88902d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 29 Aug 2026 18:20:28 +0000 Subject: [PATCH 2/4] Integrate PraxStack skills-and-personas into agent skill stack - Add install-praxstack-skills.sh with pinned ref in praxstack-skills.lock.json - Install 41 canonical + 4 public skills to .agents/skills/ (project-local) - Copy personas and workflow/goals prompts to docs/agents/ on install - Wire into extended/praxstack tiers and cloud-agent-install.sh - Document goals layer in docs/agents/goals.md and update AGENTS.md - Cherry-pick tiered install improvements (BERD_SKILLS_TIER, Context7 MCP) Co-authored-by: Prax Lannister --- .agents/skills/README.md | 24 ++- .gitignore | 7 + AGENTS.md | 8 +- docs/agents/goals.md | 62 +++++++ praxstack-skills.lock.json | 18 ++ scripts/cloud-agent-install.sh | 3 + scripts/install-agent-skills.sh | 29 ++- scripts/install-praxstack-skills.sh | 226 ++++++++++++++++++++++++ scripts/update-praxstack-skills-lock.sh | 26 +++ 9 files changed, 394 insertions(+), 9 deletions(-) create mode 100644 docs/agents/goals.md create mode 100644 praxstack-skills.lock.json create mode 100755 scripts/install-praxstack-skills.sh create mode 100755 scripts/update-praxstack-skills-lock.sh diff --git a/.agents/skills/README.md b/.agents/skills/README.md index 2a5e1b236..2069a1955 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -48,13 +48,17 @@ The install script supports three tiers via `BERD_SKILLS_TIER`: | **CORE** (default) | `core` | Layered pipeline packs (~740 skills) | | **EXTENDED** | `extended` | CORE + selective S-tier additions below | | **ALL** | `all` | EXTENDED + optional hooks (no bulk verticals) | +| **PRAXSTACK** | `praxstack` | PraxStack skills-and-personas only (no core packs) | ```bash ./scripts/install-agent-skills.sh # CORE (default) BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh +BERD_SKILLS_TIER=praxstack ./scripts/install-agent-skills.sh # PraxStack layer only +BERD_PRAXSTACK_SKILLS=1 ./scripts/install-agent-skills.sh # CORE + PraxStack +./scripts/install-praxstack-skills.sh # PraxStack only (direct) ``` -The script pins `npx skills` to the version in `skills-lock.json` (`skillsCli` field). Override with `SKILLS_CLI_VERSION=latest` if needed. +The script pins `npx skills` to the version in `skills-lock.json` (`skillsCli` field). PraxStack content is pinned in `praxstack-skills.lock.json`. Override with `SKILLS_CLI_VERSION=latest` if needed. ## Extended tier additions @@ -120,6 +124,24 @@ Re-run those skills if you switch issue trackers or change pstack model assignme - `create-pr` — open and watch PRs - `experimental-features` — experiment registry workflow +## PraxStack layer (skills-and-personas) + +[praxstack/skills-and-personas](https://github.com/praxstack/skills-and-personas) is the canonical source for PraxStack workflows: orchestration (`kingmode`, `constellation-team`), role skills (`principal-engineer`, `product-manager`, …), learning (`teach-pro-max`, `techtutor`), and leadership (`superimprove`, `cross-agent-handoff`). + +| Artifact | Install location | Install script | +| --- | --- | --- | +| **Skills** (~42 canonical + 4 public) | `.agents/skills/` | `scripts/install-praxstack-skills.sh` | +| **Personas** (multi-file packs) | `docs/agents/personas/praxstack/` | same | +| **md-personas** (single-file) | `docs/agents/personas/md/` | same | +| **Goals / workflows** (alignment, high-end-operator) | `docs/agents/workflows/praxstack/` | same | +| **Goals guide** | `docs/agents/goals.md` | checked in | + +Pin: `praxstack-skills.lock.json`. Bump with `./scripts/update-praxstack-skills-lock.sh `. + +Installed by default when `BERD_SKILLS_TIER=extended|all|praxstack`, or force with `BERD_PRAXSTACK_SKILLS=1`. Cloud Agent `cloud-agent-install.sh` runs the PraxStack installer. + +**Conflict note:** PraxStack `kingmode` / `super-mode-core` overlap conceptually with pstack `/poteto-mode` and superpowers `/writing-plans` — pick one primary planner per task (see conflict table above). + ## agent-browser CLI The browser QA layer needs the CLI alongside the skill: diff --git a/.gitignore b/.gitignore index e2614571d..c67bb9282 100644 --- a/.gitignore +++ b/.gitignore @@ -28,7 +28,14 @@ Thumbs.db # Scratch / working files .scratch/ +.cache/ .docker-cache/ + +# PraxStack install outputs (generated by scripts/install-praxstack-skills.sh) +docs/agents/praxstack-manifest.json +docs/agents/personas/praxstack/ +docs/agents/personas/md/ +docs/agents/workflows/praxstack/ .docker-home/ avatar-manifest.json project-artifacts-manifest.json diff --git a/AGENTS.md b/AGENTS.md index ef94d5334..4706742bf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -130,14 +130,18 @@ Project skills live in `.agents/skills/`. Install or refresh: ```bash ./scripts/install-agent-skills.sh # CORE tier (default) -BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh # + hallmark, deep-research, last30days +BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh # + hallmark, deep-research, last30days, PraxStack +BERD_SKILLS_TIER=praxstack ./scripts/install-agent-skills.sh # PraxStack layer only +./scripts/install-praxstack-skills.sh # PraxStack skills, personas, workflows ``` -**gstack** (`/plan-ceo-review`, `/ship`, `/qa`, …) also needs its runtime: `./scripts/install-gstack-runtime.sh` (runs automatically at the end of the skill install script). +**gstack** (`/plan-ceo-review`, `/ship`, `/qa`, …) also needs its runtime: `./scripts/install-gstack-runtime.sh` (runs automatically at the end of the skill install script when CORE tier runs). - Stack tiers, conflict warnings, and optional tools: `.agents/skills/README.md` +- PraxStack goals, personas, workflows: `docs/agents/goals.md` - MCP servers (Context7): `.cursor/mcp.json` - Skills CLI version pin: `skills-lock.json` → `skillsCli` +- PraxStack repo pin: `praxstack-skills.lock.json` ### Issue tracker diff --git a/docs/agents/goals.md b/docs/agents/goals.md new file mode 100644 index 000000000..1c4c3386a --- /dev/null +++ b/docs/agents/goals.md @@ -0,0 +1,62 @@ +# Agent goals and workflow alignment + +Berd agents should align on **what** to build before **how**. PraxStack workflow material from [skills-and-personas](https://github.com/praxstack/skills-and-personas) is vendored as prompts (not duplicate skill bodies). + +## Goals layer (when to use) + +| Situation | Entry point | Location | +| --- | --- | --- | +| Reconnect after a long break; verify shared understanding | **Align** | `docs/agents/workflows/praxstack/project-alignment/ALIGN-ONLY.md` | +| New machine / fresh clone; install packs + align + QA report | **Align + install + QA** | `docs/agents/workflows/praxstack/project-alignment/ALIGN-INSTALL-QA.md` | +| Install named packs only (gstack, Superpowers, Matt Pocock, OpenSpec, deep-research) | **Install skills** | `docs/agents/workflows/praxstack/project-alignment/INSTALL-SKILLS.md` | +| Steady engineering loop (spec → plan → build → review → ship) | **High-end operator** | `docs/agents/workflows/praxstack/high-end-operator/README.md` | + +These prompts **invoke** installed skills by name. They do not replace Berd's core stack in `.agents/skills/README.md`. + +## Steady-state loop + +For day-to-day Berd work, prefer the layered pipeline in `.agents/skills/README.md`: + +``` +discover → interrogate/spec → plan → implement → review → security → browser QA → ship → learn +``` + +Use PraxStack **goals / alignment** prompts when: + +- You no longer trust that agent and human want the same thing +- A new contributor or cloud agent needs project reconstruction +- You need constellation-team role routing (`kingmode`, `constellation-team`, `product-manager`, etc.) + +## PraxStack skills (canonical for these workflows) + +Installed by `./scripts/install-praxstack-skills.sh` into `.agents/skills/`: + +| Category | Examples | Slash / trigger | +| --- | --- | --- | +| Orchestration | `kingmode`, `super-mode-core`, `ultrathink-frontend`, `constellation-team` | Mode keywords or skill name | +| Engineering roles | `principal-engineer`, `backend-pe`, `frontend-pe`, `qa-security-engineer`, `devops-sre-engineer` | Skill name | +| Document production | `blueprint-creator`, `spec-creator`, `transcript-pipeline` | Skill name | +| Learning | `teach-pro-max`, `techtutor`, `lecture-alchemist`, `gabriel-petersson-topdown-mentor` | `/teach-pro-max`, etc. | +| Leadership | `coding-agent-leadership-principles`, `cross-agent-handoff`, `superimprove` | Skill name | + +Full inventory: run the installer, then `ls .agents/skills/ | grep -E 'kingmode|constellation|teach-pro'`. + +## Personas (reference material) + +Persona packs live under `docs/agents/personas/praxstack/` (multi-file) and `docs/agents/personas/md/` (single-file). They are **source material** for skills — not Cursor rules. Do not copy persona bodies into `.cursor/rules/`; use the distilled skills in `.agents/skills/` instead. + +## Pin and refresh + +```bash +./scripts/install-praxstack-skills.sh +# or with the full Berd stack (extended tier includes PraxStack): +BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh +``` + +Commit pin: `praxstack-skills.lock.json` → `ref` field. Bump with: + +```bash +./scripts/update-praxstack-skills-lock.sh +``` + +Manifest after install: `docs/agents/praxstack-manifest.json`. diff --git a/praxstack-skills.lock.json b/praxstack-skills.lock.json new file mode 100644 index 000000000..f76f6f269 --- /dev/null +++ b/praxstack-skills.lock.json @@ -0,0 +1,18 @@ +{ + "version": 1, + "repo": "https://github.com/praxstack/skills-and-personas.git", + "ref": "78a7ee914ae96a56e7e1ad5c27c4dca4b603dc24", + "canonicalSkillsDir": "new-skills", + "additionalSkills": [ + "teach-pro-max", + "superimprove", + "coding-agent-leadership-principles", + "cross-agent-handoff" + ], + "personasDir": "personas", + "mdPersonasDir": "md-personas", + "workflows": [ + "prompts/project-alignment", + "prompts/high-end-operator" + ] +} diff --git a/scripts/cloud-agent-install.sh b/scripts/cloud-agent-install.sh index 50dabe651..77a275b7b 100755 --- a/scripts/cloud-agent-install.sh +++ b/scripts/cloud-agent-install.sh @@ -14,5 +14,8 @@ export CI="${CI:-true}" just _setup-dev-deps GOOSE_DEV_MODE=required GOOSE_BUILD_PROFILE=debug ./scripts/ensure-local-goose.sh +# PraxStack skills-and-personas (project-local skills, personas, workflow prompts). +BERD_SKILLS_TIER=praxstack "$repo_root/scripts/install-praxstack-skills.sh" + # gstack skill markdown lives in .agents/skills/; runtime installs to ~/.claude/skills/gstack. "$repo_root/scripts/install-gstack-runtime.sh" -q diff --git a/scripts/install-agent-skills.sh b/scripts/install-agent-skills.sh index 6730019c2..b1cd78973 100755 --- a/scripts/install-agent-skills.sh +++ b/scripts/install-agent-skills.sh @@ -4,11 +4,14 @@ set -euo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" cd "$repo_root" -# Tier: core (default) | extended | all -# core — layered pipeline packs (default Berd stack) -# extended — core + selective S-tier additions (hallmark, deep-research, last30days) -# all — extended + optional verticals (none bulk-installed by default) +# Tier: core (default) | extended | all | praxstack +# core — layered pipeline packs (default Berd stack) +# extended — core + S-tier additions + PraxStack skills-and-personas +# all — extended + optional verticals (none bulk-installed by default) +# praxstack — PraxStack layer only (skills, personas, workflows) +# BERD_PRAXSTACK_SKILLS=1 forces PraxStack install at any tier (default off for core). readonly BERD_SKILLS_TIER="${BERD_SKILLS_TIER:-core}" +readonly BERD_PRAXSTACK_SKILLS="${BERD_PRAXSTACK_SKILLS:-}" # Pin skills CLI when skills-lock.json records a version (falls back to latest). skills_cli_version() { @@ -86,13 +89,20 @@ tier_at_least() { core) [[ "$want" == "core" ]] ;; extended) [[ "$want" == "core" || "$want" == "extended" ]] ;; all) true ;; + praxstack) [[ "$want" == "praxstack" ]] ;; *) - echo "error: unknown BERD_SKILLS_TIER=$BERD_SKILLS_TIER (use core|extended|all)" >&2 + echo "error: unknown BERD_SKILLS_TIER=$BERD_SKILLS_TIER (use core|extended|all|praxstack)" >&2 exit 1 ;; esac } +should_install_praxstack() { + [[ -n "$BERD_PRAXSTACK_SKILLS" && "$BERD_PRAXSTACK_SKILLS" != "0" ]] \ + || tier_at_least extended \ + || [[ "$BERD_SKILLS_TIER" == "praxstack" ]] +} + # ── CORE tier ──────────────────────────────────────────────────────────────── # Layer: discover → interrogate/spec → plan → implement → review → security → browser QA → ship → learn install_core_tier() { @@ -174,8 +184,15 @@ restore_protected_skills remove_gstack_fixtures remove_junk_dirs +if should_install_praxstack; then + "$repo_root/scripts/install-praxstack-skills.sh" + restore_protected_skills +fi + # Skill markdown is copied above; gstack also needs its runtime (bin/, browse, hooks). -"$repo_root/scripts/install-gstack-runtime.sh" +if tier_at_least core; then + "$repo_root/scripts/install-gstack-runtime.sh" +fi echo "Installed skills:" ls -1 "$repo_root/.agents/skills" | wc -l diff --git a/scripts/install-praxstack-skills.sh b/scripts/install-praxstack-skills.sh new file mode 100755 index 000000000..b0af95ea3 --- /dev/null +++ b/scripts/install-praxstack-skills.sh @@ -0,0 +1,226 @@ +#!/usr/bin/env bash +# Install PraxStack skills-and-personas into Berd (project-local). +# Skills → .agents/skills/ +# Personas → docs/agents/personas/praxstack/ +# Workflows / goals prompts → docs/agents/workflows/praxstack/ +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$repo_root" + +readonly LOCK_FILE="$repo_root/praxstack-skills.lock.json" +readonly CACHE_DIR="${PRAXSTACK_SKILLS_CACHE:-$repo_root/.cache/praxstack-skills-and-personas}" + +# Berd-owned skills that must not be overwritten. +readonly -a PROTECTED_SKILLS=( + assistive-ux + berdctl-new-command + code-review + create-pr + experimental-features +) + +is_protected() { + local name="$1" + local s + for s in "${PROTECTED_SKILLS[@]}"; do + [[ "$s" == "$name" ]] && return 0 + done + return 1 +} + +require_jq() { + if ! command -v jq >/dev/null 2>&1; then + echo "error: jq is required to read $LOCK_FILE" >&2 + exit 1 + fi +} + +lock_field() { + local field="$1" + require_jq + jq -r ".$field // empty" "$LOCK_FILE" +} + +fetch_repo() { + local git_url ref + git_url="$(lock_field repo)" + ref="$(lock_field ref)" + + if [[ -z "$git_url" || -z "$ref" ]]; then + echo "error: praxstack-skills.lock.json must set repo and ref" >&2 + exit 1 + fi + + mkdir -p "$(dirname "$CACHE_DIR")" + + if [[ -d "$CACHE_DIR/.git" ]]; then + echo "Updating PraxStack cache at $CACHE_DIR …" + git -C "$CACHE_DIR" fetch --depth 1 origin "$ref" 2>/dev/null \ + || git -C "$CACHE_DIR" fetch --depth 1 origin + git -C "$CACHE_DIR" checkout -f FETCH_HEAD 2>/dev/null \ + || git -C "$CACHE_DIR" checkout -f "$ref" 2>/dev/null \ + || true + if ! git -C "$CACHE_DIR" rev-parse --verify -q "$ref^{commit}" >/dev/null 2>&1; then + rm -rf "$CACHE_DIR" + fi + fi + + if [[ ! -d "$CACHE_DIR/.git" ]]; then + echo "Cloning $git_url @ $ref …" + git clone --depth 1 --branch "$ref" "$git_url" "$CACHE_DIR" 2>/dev/null \ + || git clone --depth 1 "$git_url" "$CACHE_DIR" + if ! git -C "$CACHE_DIR" rev-parse --verify -q "$ref^{commit}" >/dev/null 2>&1; then + git -C "$CACHE_DIR" fetch --depth 1 origin "$ref" + git -C "$CACHE_DIR" checkout -f FETCH_HEAD + else + git -C "$CACHE_DIR" checkout -f "$ref" + fi + fi + + local actual + actual="$(git -C "$CACHE_DIR" rev-parse HEAD)" + echo "PraxStack skills-and-personas @ ${actual:0:12}" +} + +copy_skill_dir() { + local src="$1" + local name + name="$(basename "$src")" + + [[ "$name" == _* ]] && return 0 + [[ "$name" == .* ]] && return 0 + [[ ! -f "$src/SKILL.md" ]] && return 0 + + if is_protected "$name"; then + echo " skip (protected): $name" + return 0 + fi + + rm -rf "$repo_root/.agents/skills/$name" + cp -R "$src" "$repo_root/.agents/skills/$name" + echo " skill: $name" +} + +install_canonical_skills() { + local skills_dir rel + rel="$(lock_field canonicalSkillsDir)" + skills_dir="$CACHE_DIR/${rel:-new-skills}" + + if [[ ! -d "$skills_dir" ]]; then + echo "error: canonical skills dir not found: $skills_dir" >&2 + exit 1 + fi + + echo "Installing PraxStack canonical skills from $rel/ …" + local src_dir + for src_dir in "$skills_dir"/*/; do + [[ -d "$src_dir" ]] || continue + copy_skill_dir "$src_dir" + done +} + +install_additional_skills() { + require_jq + local names=() + mapfile -t names < <(jq -r '.additionalSkills[]? // empty' "$LOCK_FILE") + + if [[ ${#names[@]} -eq 0 ]]; then + return 0 + fi + + echo "Installing additional public PraxStack skills …" + local name src + for name in "${names[@]}"; do + src="$CACHE_DIR/skills/$name" + if [[ ! -d "$src" ]]; then + echo " warn: missing skills/$name" >&2 + continue + fi + copy_skill_dir "$src" + done +} + +copy_tree() { + local src="$1" + local dest="$2" + rm -rf "$dest" + mkdir -p "$dest" + cp -R "$src"/. "$dest/" +} + +install_personas() { + local personas_src="$CACHE_DIR/$(lock_field personasDir)" + local md_src="$CACHE_DIR/$(lock_field mdPersonasDir)" + local dest="$repo_root/docs/agents/personas/praxstack" + local md_dest="$repo_root/docs/agents/personas/md" + + if [[ -d "$personas_src" ]]; then + echo "Installing personas → docs/agents/personas/praxstack/ …" + copy_tree "$personas_src" "$dest" + fi + + if [[ -d "$md_src" ]]; then + echo "Installing md-personas → docs/agents/personas/md/ …" + copy_tree "$md_src" "$md_dest" + fi +} + +install_workflows() { + require_jq + local dest="$repo_root/docs/agents/workflows/praxstack" + mkdir -p "$dest" + + echo "Installing workflow / goals prompts → docs/agents/workflows/praxstack/ …" + local rel target_name + while IFS= read -r rel; do + [[ -n "$rel" ]] || continue + target_name="$(basename "$rel")" + if [[ -d "$CACHE_DIR/$rel" ]]; then + copy_tree "$CACHE_DIR/$rel" "$dest/$target_name" + else + echo " warn: missing workflow path $rel" >&2 + fi + done < <(jq -r '.workflows[]? // empty' "$LOCK_FILE") +} + +write_manifest() { + local manifest="$repo_root/docs/agents/praxstack-manifest.json" + require_jq + jq -n \ + --arg ref "$(git -C "$CACHE_DIR" rev-parse HEAD)" \ + --arg installedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + --arg lock "$LOCK_FILE" \ + '{ + source: "praxstack/skills-and-personas", + lockFile: $lock, + ref: $ref, + installedAt: $installedAt, + skillsDir: ".agents/skills/", + personasDir: "docs/agents/personas/praxstack/", + mdPersonasDir: "docs/agents/personas/md/", + workflowsDir: "docs/agents/workflows/praxstack/", + goalsDoc: "docs/agents/goals.md" + }' > "$manifest" + echo "Wrote $manifest" +} + +main() { + if [[ ! -f "$LOCK_FILE" ]]; then + echo "error: missing $LOCK_FILE" >&2 + exit 1 + fi + + fetch_repo + install_canonical_skills + install_additional_skills + install_personas + install_workflows + write_manifest + + local count + count="$(find "$repo_root/.agents/skills" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')" + echo "PraxStack layer complete. Total skills in .agents/skills/: $count" +} + +main "$@" diff --git a/scripts/update-praxstack-skills-lock.sh b/scripts/update-praxstack-skills-lock.sh new file mode 100755 index 000000000..c465860a0 --- /dev/null +++ b/scripts/update-praxstack-skills-lock.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# Resolve and record a new pin for praxstack/skills-and-personas. +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +lock_file="$repo_root/praxstack-skills.lock.json" + +ref="${1:-main}" +git_url="$(jq -r '.repo // "https://github.com/praxstack/skills-and-personas.git"' "$lock_file")" + +if ! command -v jq >/dev/null 2>&1; then + echo "error: jq required" >&2 + exit 1 +fi + +resolved="$(git ls-remote "$git_url" "$ref" | awk 'NR==1 {print $1}')" +if [[ -z "$resolved" ]]; then + echo "error: could not resolve $ref from $git_url" >&2 + exit 1 +fi + +tmp="$(mktemp)" +jq --arg ref "$resolved" '.ref = $ref' "$lock_file" > "$tmp" +mv "$tmp" "$lock_file" + +echo "Updated $lock_file → ref=$resolved ($ref)" From 0da55ea882bc9aa8a82947a249c6329cda6ff15d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 30 Aug 2026 16:23:36 +0000 Subject: [PATCH 3/4] Fix PraxStack install: gitignore skills, verify lock pin, harden lock script - Add .agents/skills/.gitignore for 45 install-time PraxStack skill dirs - Fail install when cache HEAD does not match praxstack-skills.lock.json ref - Guard update-praxstack-skills-lock.sh when lock file is missing - Remove unused BERD_SKILLS_TIER from cloud-agent-install.sh Co-authored-by: Prax Lannister --- .agents/skills/.gitignore | 48 +++++++++++++++++++++++++ scripts/cloud-agent-install.sh | 2 +- scripts/install-praxstack-skills.sh | 12 ++++++- scripts/update-praxstack-skills-lock.sh | 5 +++ 4 files changed, 65 insertions(+), 2 deletions(-) create mode 100644 .agents/skills/.gitignore diff --git a/.agents/skills/.gitignore b/.agents/skills/.gitignore new file mode 100644 index 000000000..1ea7c461f --- /dev/null +++ b/.agents/skills/.gitignore @@ -0,0 +1,48 @@ +# PraxStack install-time skills (generated by scripts/install-praxstack-skills.sh). +# Not vendored in git — refresh via ./scripts/install-praxstack-skills.sh or extended tier. +# When praxstack-skills.lock.json adds skills, update this file in the same commit. +/apex-autonomous-mode/ +/autonomous-orchestrion/ +/backend-architecture-standards/ +/backend-pe-cpp/ +/backend-pe-java/ +/backend-pe-javascript/ +/backend-pe-nodejs/ +/backend-pe-python-ml/ +/backend-pe-python/ +/backend-pe-typescript/ +/backend-pe/ +/backend-system-design-expert/ +/baron-von-markup/ +/blueprint-creator/ +/chronicle/ +/coding-agent-leadership-principles/ +/concept-cartographer/ +/constellation-team/ +/cross-agent-handoff/ +/devops-sre-engineer/ +/frontend-design-excellence/ +/frontend-excellence-standards/ +/frontend-pe/ +/frontend-uiux-designer/ +/gabriel-petersson-topdown-mentor/ +/idea-capturer/ +/kingmode/ +/lecture-alchemist/ +/mental-health-screening-companion/ +/obsidian-cli/ +/orchestrion-universal-agent-router/ +/principal-engineer/ +/product-manager/ +/professor-alex-interview/ +/qa-security-engineer/ +/security-compliance-standards/ +/spec-creator/ +/super-mode-core/ +/superimprove/ +/svg-logo-designer/ +/teach-pro-max/ +/techtutor/ +/transcribe-refiner/ +/transcript-pipeline/ +/ultrathink-frontend/ diff --git a/scripts/cloud-agent-install.sh b/scripts/cloud-agent-install.sh index 77a275b7b..bb704d1a0 100755 --- a/scripts/cloud-agent-install.sh +++ b/scripts/cloud-agent-install.sh @@ -15,7 +15,7 @@ just _setup-dev-deps GOOSE_DEV_MODE=required GOOSE_BUILD_PROFILE=debug ./scripts/ensure-local-goose.sh # PraxStack skills-and-personas (project-local skills, personas, workflow prompts). -BERD_SKILLS_TIER=praxstack "$repo_root/scripts/install-praxstack-skills.sh" +"$repo_root/scripts/install-praxstack-skills.sh" # gstack skill markdown lives in .agents/skills/; runtime installs to ~/.claude/skills/gstack. "$repo_root/scripts/install-gstack-runtime.sh" -q diff --git a/scripts/install-praxstack-skills.sh b/scripts/install-praxstack-skills.sh index b0af95ea3..37cb8a9b3 100755 --- a/scripts/install-praxstack-skills.sh +++ b/scripts/install-praxstack-skills.sh @@ -78,8 +78,18 @@ fetch_repo() { fi fi - local actual + verify_pin +} + +verify_pin() { + local expected actual + expected="$(lock_field ref)" actual="$(git -C "$CACHE_DIR" rev-parse HEAD)" + if [[ "$actual" != "$expected" ]]; then + echo "error: PraxStack cache at ${actual:0:12}, lock requires ${expected:0:12}" >&2 + echo " Delete $CACHE_DIR or run ./scripts/update-praxstack-skills-lock.sh" >&2 + exit 1 + fi echo "PraxStack skills-and-personas @ ${actual:0:12}" } diff --git a/scripts/update-praxstack-skills-lock.sh b/scripts/update-praxstack-skills-lock.sh index c465860a0..e04a6da6b 100755 --- a/scripts/update-praxstack-skills-lock.sh +++ b/scripts/update-praxstack-skills-lock.sh @@ -5,6 +5,11 @@ set -euo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" lock_file="$repo_root/praxstack-skills.lock.json" +if [[ ! -f "$lock_file" ]]; then + echo "error: missing $lock_file" >&2 + exit 1 +fi + ref="${1:-main}" git_url="$(jq -r '.repo // "https://github.com/praxstack/skills-and-personas.git"' "$lock_file")" From bcb62bbdbd774eed4dcaceb4c04d54fde94baf84 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 30 Aug 2026 16:23:55 +0000 Subject: [PATCH 4/4] Format praxstack-skills.lock.json for biome Co-authored-by: Prax Lannister --- praxstack-skills.lock.json | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/praxstack-skills.lock.json b/praxstack-skills.lock.json index f76f6f269..977ce884b 100644 --- a/praxstack-skills.lock.json +++ b/praxstack-skills.lock.json @@ -11,8 +11,5 @@ ], "personasDir": "personas", "mdPersonasDir": "md-personas", - "workflows": [ - "prompts/project-alignment", - "prompts/high-end-operator" - ] + "workflows": ["prompts/project-alignment", "prompts/high-end-operator"] }