the-grid

What it is

the-grid is not a framework and not skills-only. It wires skills from across the ecosystem, composes and wires AI dev-team agents, and makes spec-driven development the default for the projects it scaffolds. Machines, MCP servers, prompts, and configs are already growing in.

The core mechanic: a single script (wire.sh) symlinks skills and composed agents into ~/.claude/skills/ and ~/.claude/agents/ so Claude picks them up automatically — no installs, no config files. the-grid owns some assets directly and pulls many more from sibling repos via git submodules.

The two tiers

agent-factory — composed agents

agent-factory/ composes AI dev-team agents from three orthogonal inputs: role × stack × skills. Each input is independent — swap a stack overlay without touching the role's identity, or bolt on a skill without rewriting anything else.

A compose config names a project and lists agents, each as role + stacks[] + skills[] + model. compose.py reads it and emits one folder per agent under agent-factory/projects/<name>/, rendered to the live OpenClaw 5-file identity model: SOUL.md (how it behaves), IDENTITY.md (who it is + model), AGENTS.md (boot sequence + async handoff), USER.md (who it serves), MEMORY.md (what it carries).

compose.py is a multi-target compiler — one 5-file source, a different artefact shape per --target. The claude-code target splits on role.yaml orchestrator:

# Compose each public project for the Claude Code target
.venv/bin/python agent-factory/compose.py agent-factory/examples/core.yaml --target claude-code
.venv/bin/python agent-factory/compose.py agent-factory/examples/grid.yaml --target claude-code
.venv/bin/python agent-factory/compose.py agent-factory/examples/finance-desk.yaml --target claude-code
.venv/bin/python agent-factory/compose.py agent-factory/examples/learning-desk.yaml --target claude-code

# Wire the output — orchestrators → ~/.claude/skills/, specialists → ~/.claude/agents/
bash scripts/wire.sh

# Open a fresh Claude Code session to pick up the new agents, then:
# /grid-tech-lead    ← invoke the orchestrator

automation-factory — reusable patterns

A sibling factory to agent-factory/, one tier down: not composed agents, but reusable automation patterns — the orchestration layer that wires an agent into a recurring, unattended workflow. A tailor doesn't sew each suit from scratch — they cut from a pattern. Each pattern is a generic, version-controlled template, instantiated (cut + placeholder-filled) into a target repo's tracked loop/ folder — not .claude/, which is commonly gitignored and wouldn't survive a clone or repo move.

First pattern: issue-loop — an agent that works a repo's labelled GitHub issues and hands a verified pull request to a human, one issue per run. Composes a headless runner with a /loop prompt and a post-commit review hook.

project-factory — project bootstrapping

Scaffolds whole new projects from a template — a different job from skills/ (wired), agent-factory/ (composes personas), and automation-factory/ (cuts a pattern into an existing repo). A template is standalone: no logic of its own, doesn't run, doesn't depend on the-grid once cut.

project-factory/scripts/cut-project.sh <template> <target-dir> either seeds a brand-new project (empty target) or retrofits an existing one (non-empty target) — same script, same rule either way: never overwrite a file that already exists and differs from the template; anything skipped is reported for manual review. Composition (which agent-factory persona, which skills, which automation-factory pattern) happens after seeding, as a normal step in the resulting repo.

Specs — spec-driven development

the-grid wires OpenSpec (Fission-AI/openspec, MIT) on every machine — 12 skills covering explore → propose → apply → verify → archive. Specs live in the repo as plain markdown, so a plan outlives the session that produced it, and a proposal gets reviewed before any code exists.

There is deliberately no fifth factory here. OpenSpec already is the spec factory; rebuilding propose/apply/archive would be reimplementing it badly. the-grid adds two thin layers instead:

• project-factory/templates/_common/SPECS.md — the convention plus agent instructions, laid down on every cut project, seed or retrofit. Spec-driven becomes the default rather than a per-project decision someone has to remember to make.
• agent-factory/_core/AGENTS_base.md — a boot-sequence check for SPECS.md / openspec/. One edit reaches every composed agent. Conditional: repos without those markers are untouched.

/openspec-help is the reference card. /spec-scout audits adoption and reports drift between the specs and what the code actually does — survey-only, it never writes a spec.

External dependency. These skills shell out to a CLI that isn't vendored, and pull their real instructions from it at runtime — without it they load and dead-end immediately: npm install -g @fission-ai/openspec@1.12.0 (needs Node ≥ 20.19.0). openspec init is optional — openspec new change bootstraps the openspec/ tree on its own.

Agents

agent-factory produces 40 roles across four independently composed and gated public projects (plus any private desk composed the same way, sourcing roles from outside this repo — see CLAUDE.md). Eight roles are orchestrators — they become Claude Code skills invoked as slash commands; five coordinate a team (one, gsd, is the light fan-out for small fixes), and three (tron, morpheus, oracle) talk to you directly. The other 32 are specialists — subagents delegated to by an orchestrator or called directly.

core cross-desk infra — stays wired everywhere

grid dev team — engineering, product, marketing

finance-desk standalone — not part of the CEO's chain

learning-desk manual — you start every session; data stays private

Skills

132 wired live (14 root-owned + 118 from allowlisted repos) across 8 sources — active in every Claude session. Another 100 exist in those same partial repos but aren't wired, and a further over 1,000 are indexed across 19 dedicated library submodules — all searchable via skill-scout, none loaded by default.

Not sure which one you want? Three reference cards answer that — /grid-help (the repo as a whole), /openspec-help (the spec workflow), and /ponytail-help (the minimum-diff modes). Each prints once and stops.

Root (owned / edited) 14 wired

• caveman — Ultra-compressed communication mode.
• gh-issues-by-severity — List open GitHub issues grouped by severity, discovering whatever severity:* label scheme the repo actually uses.
• grid-help — Live in-session guide to using the-grid — which slash command or subagent to reach for.
• grill-me — A relentless interview to sharpen a plan or design.
• handoff — Compact the current conversation into a handoff document for another agent to pick up.
• mine-learnings — Mine project history for durable technical learnings and fold the highest-value ones into CLAUDE.md.
• openspec-help — Reference card for the 12 openspec skills — which to reach for, the spec format, and how the convention reaches new and existing projects.
• rubber-duck — Structured rubber duck debugging.
• setup-repo-skills — Sets up an Agent skills block in AGENTS.md/CLAUDE.md and docs/agents/ so engineering skills know this repo's issue tracker, triage labels, and domain details.
• skill-scout — Scout public agent-skill directories (ranked by installs) and propose new skills to add to the-grid, deduped against what's already wired.
• spec-scout — Audit a repo's OpenSpec adoption and report drift between specs and shipped code. Survey-only — never writes specs.
• standup — Generate a concise standup summary from recent git activity across repos.
• tighten — Condense verbose prose across project docs — cuts filler and hedging without dropping facts.
• un-claudish — Post-processing editor that purges Claude-isms, rhetorical tropes, AI cadence, and em-dash saturation to convert drafts into crisp, executive business prose.

repos/openspec 12 wired

• openspec-apply-change — Implement the tasks from an approved change.
• openspec-archive-change — Fold the delta into the main specs and move the change to archive.
• openspec-bulk-archive-change — Archive several parallel changes at once.
• openspec-continue-change — Pick up a change a previous session left half-built.
• openspec-explore — Thinking partner for exploring a problem before committing to a direction. Writes nothing.
• openspec-ff-change — Fast-forward — generate every artefact without stepping through each one.
• openspec-new-change — Step-by-step artefact creation instead of the one-shot propose.
• openspec-onboard — Guided first cycle, narrated, doing real work in your codebase.
• openspec-propose — Create a change and generate every artefact in one pass — proposal, spec delta, design, tasks.
• openspec-sync-specs — Push a delta into the main specs without archiving the change.
• openspec-update-change — Revise an existing plan and keep its artefacts coherent. Never edits code.
• openspec-verify-change — Check the implementation actually matches the change artefacts before archiving.

repos/anthropic 9 wired

• claude-api — Reference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, caching.
• docx — Create, read, edit, or manipulate Word documents (.docx files).
• internal-comms — Write all kinds of internal communications using company-preferred formats.
• mcp-builder — Guide for creating high-quality MCP servers that enable LLMs to interact with external services.
• pdf — Do anything with PDF files.
• pptx — Handle .pptx files as input, output, or both.
• skill-creator — Create new skills, modify and improve existing skills, and measure skill performance.
• template-skill — Starter template for new skills.
• xlsx — Handle spreadsheet files as primary input or output.

Desktop/design tools (brand-guidelines, canvas-design, frontend-design, theme-factory, web-artifacts-builder, webapp-testing) are wired via machine overlays, not the baseline.

repos/gstack 42 wired

• autoplan — Auto-review pipeline — CEO, design, eng, and DX reviews run sequentially with auto-decisions.
• benchmark — Performance regression detection using the browse daemon.
• browse — Fast headless browser for QA testing and site dogfooding.
• canary — Post-deploy canary monitoring.
• careful — Safety guardrails for destructive commands.
• codex — OpenAI Codex CLI wrapper — three modes.
• context-restore — Restore working context saved earlier by /context-save.
• context-save — Save working context.
• cso — Chief Security Officer mode.
• design-consultation — Research the landscape, propose a complete design system, and generate font + color previews.
• design-html — Design finalization: generate production-quality Pretext-native HTML/CSS.
• design-review — Designer's eye QA: find visual inconsistencies, spacing issues, hierarchy problems — then fix them.
• design-shotgun — Generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate.
• devex-review — Live developer experience audit.
• document-generate — Generate missing documentation from scratch for a feature, module, or entire project.
• document-release — Post-ship documentation update.
• freeze — Restrict file edits to a specific directory for the session.
• guard — Full safety mode: destructive command warnings + directory-scoped edits.
• health — Code quality dashboard.
• investigate — Systematic debugging with root cause investigation.
• land-and-deploy — Land and deploy workflow.
• landing-report — Read-only queue dashboard for workspace-aware ship.
• learn — Manage project learnings.
• make-pdf — Turn any markdown file into a publication-quality PDF.
• office-hours — YC Office Hours — two modes.
• pair-agent — Pair a remote AI agent with your browser.
• plan-ceo-review — CEO/founder-mode plan review.
• plan-design-review — Designer's eye plan review — interactive, like CEO and Eng review.
• plan-devex-review — Interactive developer experience plan review.
• plan-eng-review — Eng manager-mode plan review.
• plan-tune — Self-tuning question sensitivity + developer psychographic for gstack.
• qa — Systematically QA test a web application and fix bugs found.
• qa-only — Report-only QA testing.
• retro — Weekly engineering retrospective.
• review — Pre-landing PR review.
• scrape — Pull data from a web page.
• setup-browser-cookies — Import cookies from your real Chromium browser into the headless browse session.
• setup-deploy — Configure deployment settings for /land-and-deploy.
• ship — Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR.
• skillify — Codify the most recent successful /scrape flow into a permanent browser-skill on disk.
• spec — Turn vague intent into a precise, executable spec in five phases.
• unfreeze — Clear the freeze boundary set by /freeze, allowing edits to all directories again.

OpenClaw-specific tools (gstack-openclaw-*, setup-gbrain, sync-gbrain, open-gstack-browser) and benchmark-models are wired via machine overlays, not the baseline.

repos/jeffallan 18 wired

• architecture-designer — Design new high-level system architecture, review existing designs, or make architectural decisions.
• cli-developer — Build CLI tools, implement argument parsing, or add interactive prompts.
• code-documenter — Generate, format, and validate technical documentation — docstrings, OpenAPI/Swagger specs, JSDoc, doc portals, and user guides.
• code-reviewer — Analyze code diffs to identify bugs, security vulnerabilities, code smells, N+1 queries, and architectural concerns.
• database-optimizer — Optimize database queries and improve performance across PostgreSQL and MySQL systems.
• debugging-wizard — Parse error messages, trace execution flow through stack traces, and apply systematic hypothesis-driven methodology to isolate bugs.
• devops-engineer — Create Dockerfiles, configure CI/CD pipelines, write Kubernetes manifests, and generate Terraform/Pulumi infrastructure templates.
• feature-forge — Conduct structured requirements workshops to produce feature specs, user stories, EARS-format requirements, and acceptance criteria.
• legacy-modernizer — Design incremental migration strategies, identify service boundaries, produce dependency maps and migration roadmaps.
• mcp-developer — Build, debug, or extend MCP servers or clients that connect AI systems with external tools and data sources.
• postgres-pro — Optimize PostgreSQL queries, configure replication, or implement advanced database features.
• prompt-engineer — Write, refactor, and evaluate prompts for LLMs — generating optimized templates, structured output schemas, and evaluation rubrics.
• secure-code-guardian — Implement authentication/authorization, secure user input, or prevent OWASP Top 10 vulnerabilities.
• security-reviewer — Identify security vulnerabilities, generate structured audit reports with severity ratings, and provide remediation guidance.
• spec-miner — Reverse-engineering specialist that extracts specifications from existing codebases.
• sql-pro — Optimize SQL queries, design database schemas, and troubleshoot performance issues.
• test-master — Generate test files, create mocking strategies, analyze coverage, and produce test plans across functional, performance, and security testing.
• the-fool — Challenge ideas, plans, decisions, or proposals using structured critical reasoning.

Stack-specific packs (LAMP, data/ML, infra/SRE — chaos-engineer, cpp-pro, fullstack-guardian, javascript-pro, laravel-specialist, microservices-architect, ml-pipeline, monitoring-expert, nestjs-expert, nextjs-developer, pandas-pro, php-pro, playwright-expert, python-pro, rag-architect, sre-engineer, vue-expert, vue-expert-js, websocket-engineer, wordpress-pro) live in machine overlays, not the baseline.

repos/mattpocock 17 wired

• diagnosing-bugs — Diagnosis loop for hard bugs and performance regressions.
• git-guardrails-claude-code — Set up Claude Code hooks to block dangerous git commands before they execute.
• grill-me — Interview the user relentlessly about a plan or design until reaching shared understanding.
• grill-with-docs — Grilling session that challenges your plan against the existing domain model and updates documentation inline as decisions crystallise.
• grilling — Grill the user relentlessly about a plan, decision, or idea.
• improve-codebase-architecture — Find deepening opportunities in a codebase, informed by CONTEXT.md and docs/adr/.
• scaffold-exercises — Create exercise directory structures with sections, problems, solutions, and explainers that pass linting.
• setup-pre-commit — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo.
• tdd — Test-driven development with red-green-refactor loop.
• teach — Teach the user a new skill or concept, within this workspace.
• to-spec — Turn the current conversation into a spec and publish it to the project issue tracker.
• to-tickets — Break a plan, spec, or conversation into tracer-bullet tickets that declare their blocking edges, published to the configured tracker.
• triage — Triage issues through a state machine driven by triage roles.
• writing-beats — Shape an article as a journey of beats, choose-your-own-adventure style.
• writing-for-agents — Writing documents for agents.
• writing-fragments — Mine the user for fragments — heterogeneous nuggets of writing — and append them to a single document as raw material.
• writing-shape — Take a markdown file of raw material and shape it into an article through a conversational session.

Design/personal tools (design-an-interface, obsidian-vault, prototype) live in machine overlays.

repos/ponytail 6 wired

• ponytail — Forces the laziest solution that actually works — simplest, shortest, most minimal.
• ponytail-audit — Whole-repo audit for over-engineering — a ranked list of what to delete, simplify, or replace.
• ponytail-debt — Harvest every `ponytail:` comment into a debt ledger, so deferrals get tracked instead of forgotten.
• ponytail-gain — Show ponytail's measured impact as a compact scoreboard: less code, less cost, more speed.
• ponytail-help — Quick-reference card for all ponytail modes, skills, and commands.
• ponytail-review — Review a diff for over-engineering.

Wired whole (all skills in the repo), unlike the partial repos above — wanted live everywhere.

repos/superpowers 14 wired

• brainstorming — Use before any creative work: creating features, building components, adding functionality, or modifying behavior.
• dispatching-parallel-agents — Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies.
• executing-plans — Use when you have a written implementation plan to execute in a separate session with review checkpoints.
• finishing-a-development-branch — Use when implementation is complete and all tests pass — guides completion via structured options for merge, PR, or cleanup.
• receiving-code-review — Use when receiving code review feedback, before implementing suggestions — requires technical rigor and verification.
• requesting-code-review — Use when completing tasks or before merging to verify work meets requirements.
• subagent-driven-development — Use when executing implementation plans with independent tasks in the current session.
• systematic-debugging — Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.
• test-driven-development — Use when implementing any feature or bugfix, before writing implementation code.
• using-git-worktrees — Use when starting feature work that needs isolation from the current workspace.
• using-superpowers — Use when starting any conversation — establishes how to find and use skills.
• verification-before-completion — Use when about to claim work is complete — requires running verification commands and confirming output before any success claims.
• writing-plans — Use when you have a spec or requirements for a multi-step task, before touching code.
• writing-skills — Use when creating new skills, editing existing skills, or verifying skills work before deployment.

Key files

Common commands

git clone https://github.com/oneafrikan/the-grid.git ~/.the-grid \
  && bash ~/.the-grid/scripts/bootstrap.sh
# add --with-agents to also compose + wire the agent team in the same run

npm install -g @fission-ai/openspec@1.12.0
# needs Node >= 20.19.0. The 12 wired openspec-* skills dead-end without it.

bash scripts/check-grid.sh
# runs the bats suite + scans for broken grid-owned symlinks; exits non-zero on failure

bash scripts/sources.sh --check
# link-checks every submodule upstream URL — catches renamed/deleted repos

mkdir ~/.the-grid/skills/my-skill
# create SKILL.md with name: and description: frontmatter
bash scripts/wire.sh

bash scripts/catalog.sh
# wire.sh calls this automatically — rarely needed standalone

git submodule add <repo-url> repos/<name>
git submodule update --init
bash scripts/wire.sh
# To wire it live everywhere: add repos/<name> to baseline-submodules.txt, then re-run wire.sh
# To wire it on one machine only: add it to machines/<host>.txt instead

bash project-factory/scripts/cut-project.sh <template> <target-dir>
# seeds an empty target, or retrofits a non-empty one — never overwrites a differing file
# every cut gets _common/SPECS.md — the OpenSpec convention is on by default

cd agent-factory
GRID_PRIVATE_ROLES_DIR=~/path/to/private/roles \
  .venv/bin/python compose.py ~/path/to/private/projects/<name>.yaml --target claude-code
cd .. && bash scripts/wire.sh
# gate it with project:<name> in machines/<host>.local.txt (gitignored)
#
# WARNING: compose.py overwrites projects/<name>/ wholesale. Recomposing the
# public projects while a private project's roles are unreachable destroys its
# composed output, and the next wire.sh removes its symlinks.

bash scripts/reconcile.sh          # dry run — list shadowing dirs
bash scripts/reconcile.sh --force  # move aside to a dated backup dir + re-wire

tests/lib/bats-core/bin/bats tests/

Roadmap

compose.py is a multi-target compiler: one source — the OpenClaw 5-file identity model (SOUL/IDENTITY/AGENTS/USER/MEMORY + skills) — emitting to different runtimes. Adding a target means writing an emitter, not re-authoring a single agent.

Shipped: the Claude Code target is built and wired live. --target also accepts openclaw, openclaw-native, paperclip, codex, gemini-cli, opencode and portable (single-file personas in dist/personas/). Skills, subagents and rule packs reach Codex CLI, OpenCode and Gemini CLI through opt-in harness:<name> manifest entries; Cursor gets rule packs only (scripts/rules.py emit --harness cursor).

Not built, or not yet verified — tracked in Issues:

Model routing across providers (OpenRouter and friends) is a live question, not a built feature — docs/model-selection.md carries the current price and capability picture, plus the evidence gaps in it.

Status & expectations

This is one person's working system, shared because the mechanics are reusable — not a supported product. Concretely:

• It will change under you. No versioning, no deprecation cycle.
• It is opinionated and partly personal. Personal config (machine overlays, your baseline, the dev-journal) is gitignored or kept in a private repo, and scripts/check-personal.sh scans the tracked tree for personal data.
• Fork rather than depend. The wiring model — manifest, symlinks, compose-then-wire — is the transferable part. Copy it and point it at your own skills.
• wire.sh only replaces symlinks that point into this repo. It won't clobber a real directory or a foreign symlink in ~/.claude/skills/. It also edits ~/.claude/settings.json (the auto-handoff hook, on by default). Read it before running it anyway — it writes to your home directory.