Spec Driven

An orchestrator-first collection of Agent Skills for spec-driven development: the orchestrator skill turns a PRD or idea into approved SPECs, tracked GitHub Issues, TDD-implemented slices, QA gates, and reviewed PRs — across Claude Code, OpenCode, Devin, Cursor, and other runtimes.

🚀 Overview

This repository implements Spec-Driven Development (SDD) for AI agents, following the Agent Skills Specification (agentskills.io). At the center is the orchestrator skill: a control loop that audits preconditions, provisions the agent harness, consolidates domain language into approved SPEC SDDs (.specs/SPEC-*.md), fragments work into GitHub Issues, and delegates implementation, review, QA, and documentation to specialized skills — never doing complex work itself.

Every other skill in the catalog is a delegation target in that loop. Instead of generic prompts, each skill provides structured patterns, constraints, and reference materials that allow agents to perform complex software engineering tasks with production-grade quality.

🧭 The Orchestrator

The orchestrator is the entry point and central control skill for agent-driven projects. Invoke it with /spec-driven (alias for /spec-driven:orchestrator, or "use the orchestrator skill") and it runs a continuous loop, delegating complex work to specialized skills and persisting state in .claude/memory/orchestrator_stats.md.

flowchart TD
    A[Phase -1: Framework Update] --> B[Phase 0: Governance]
    B --> C[Phase 1: Discovery]
    C --> D[Phase 2: Audit]
    D --> E[Phase 3: GitHub Fragmentation]
    E --> F[Phase 4: Implementation Loop]
    F --> G[Phase 5: Verification & QA]
    G --> H[PR / Merge]

    C -->|PRD only| I[/scaffold-mvp\]
    C -->|needs spec| J[/write-specs\]
    D -->|P2 gap| K[/improve-codebase-architecture\]
    E --> L[/create-issues\]
    F -->|per slice| M[/execute-specs\]
    F -->|bug| N[/diagnose\]
    G --> O[/qa-analyst\]
    G --> P[/architecture\]
    G --> R[/gap-analysis\]

    S[/migration-planner\] -.->|domain plans| J
    T[/web-design-guidelines\] -.->|finding groups| J

Loading

The orchestrator advances automatically between phases once validation passes. It only pauses for escalation gates (security, schema, public APIs, data changes), validation failures, or an explicit user request to stop.

🛠️ Skill Catalog & Correlation

The skills are organized around the orchestrator's pipeline: Harness Engineering, Orchestration & Delivery, Code Quality & Review, Frontend & Design, Extensibility & Integration, and MCP Integrations.

🏗️ Harness Engineering

Foundation for creating and managing AI agents.

• create-agent-harness: The starting point. Use this to bootstrap a complete agent environment (CLAUDE.md, rules, skills) in any repo.
• create-readme: Professionalizes the repository landing page. Generates evidence-based READMEs and SemVer-compliant CHANGELOGs.
• observability-and-instrumentation: Once the harness is set, use this to ensure the agent's actions and the application's behavior are visible and diagnosable in production.

🧭 Orchestration & Delivery

Planning, execution, verification, and documentation for agent-driven projects.

• orchestrator: Central control skill. Audits preconditions, creates documentation, reconciles open GitHub Issues, turns gaps into Issues, and coordinates execution, tests, QA, and PR in a continuous loop. Persists state in .claude/memory/orchestrator_stats.md and auto-continues to the next slice.
• write-specs: Interviews the user in Portuguese to consolidate domain language and produce an approved .specs/SPEC-{YYYYMMDD}-{feature}.md before implementation.
• scaffold-mvp: Bootstraps a new .NET/Blazor/Angular repository after domain/spec alignment. Installs the agent harness, proposes a productive stack, and generates the initial project skeleton, AD-0001, and stubs.
• create-issues: Turns approved gaps, roadmap, and specs into GitHub Issues with vertical slices and dependency links. Uses the references/spec-sdd-template.md structure when creating Issues from SPEC SDDs.
• execute-specs: Test-driven development using the approved SPEC SDD as the source of truth. Red-green-refactor one vertical slice at a time.
• qa-analyst: Full QA cycle — requirements analysis, test planning, test cases, execution, bug reports, and process improvement.
• diagnose: Disciplined diagnosis and re-validation loop for hard bugs and performance regressions — tight feedback loops, ranked falsifiable hypotheses, stack playbooks for .NET/Angular/Python/React, agent self-debug, and AI workflow audit.
• improve-codebase-architecture: Finds architectural deepening opportunities by reading .claude/CONTEXT.md, .claude/MEMORY.md, and docs/architecture/, and produces an HTML report.
• architecture: The single owner of docs/architecture/. Routes ADRs, design docs, and diagrams to drawio-architecture, mermaid-architecture, and the optional archify skill (interactive HTML, used only when already installed — never installed at runtime), then ends with the gap-analysis evidence audit it owns.
• gap-analysis: Evidence-backed audit of AS-IS code vs. TO-BE specs/docs. Confirmed gaps become Draft SPECs (write-specs), a tracked Epic with slices (create-issues), and orchestrated execution (orchestrator) — behind an explicit approval gate.
• migration-planner: Evidence-based legacy → .NET migration planning with the Strangler Fig pattern. Researches the codebase, maps bounded contexts, designs seams (YARP, DI, EF Core dual-write, Blazor/MAUI), writes per-domain plans + roadmap in migration-plan/, then converts each domain into Draft SPECs (write-specs), a tracked Epic (create-issues), and orchestrated execution (orchestrator) — behind an explicit approval gate. Default targets: Blazor WebAssembly, .NET MAUI, ASP.NET Core.

💎 Code Quality & Review

Ensuring the output meets professional standards.

• code-review-and-quality: The primary gatekeeper. Performs multi-axis reviews (correctness, security, performance) before any code is merged.
• quality-test-implementation: The whole-repo quality intervention. Fixes static-analysis warnings (Roslyn/Sonar, SpotBugs/Checkstyle, Bandit/Ruff), resolves security CVEs, and applies SOLID/DDD/Clean Architecture across .NET, Java, or Python repositories.
• sonarqube-autofix: The automated auditor. Integrates with SonarQube to identify and fix technical debt and smells systematically.

🔬 Security & Reverse Engineering

Authorized analysis of shipped artifacts, protocols, and adversarial surfaces.

• reverse-engineer: Consolidated RE hub merging REA (rea-agents CLI/MCP, evidence-ledger workflows) with the reverse-skill domain pack — 40+ guides covering binaries, APK/mobile, JS/Electron, .NET, firmware, protocols, malware, CTF, and authorized pentest lanes. Includes a deterministic router (master-route.sh), case/scope gates (case-init.sh, auth.status=granted required before ACT), a per-module tool-readiness checker (check-tools.sh), and an REA installer (install-rea.sh).

🎨 Frontend & Design

Shaping user-facing interfaces with mobile-first, responsive craft.

• design: Frontend UI design for Angular, React, and Blazor. Covers mobile-first responsive layouts, typography, color, components, accessibility, motion, design tokens, Bootstrap/Tailwind CSS examples, and production hardening.
• web-design-guidelines: Web design validation, merged from vercel-labs/web-design-guidelines + lighthouse-95. Audits UI files against the complete interface-guidelines rule set (file:line findings, with Angular/Blazor mappings) and/or verifies deployed pages against Lighthouse 95+ (mobile + desktop, 3-run verdicts), then converts confirmed pendencies into Draft SPECs (write-specs), an Epic + Issues (create-issues), and orchestrated fixes (orchestrator).

🔌 Extensibility & Integration

Expanding what the agent can actually do.

• building-mcp-servers: The power-user tool. Teaches agents how to build their own Model Context Protocol (MCP) servers to connect to any API or database.
• drawio-architecture: Visual intelligence. Merges architecture diagram authoring with the official draw.io MCP server for automated system design.
• mermaid-architecture: Diagrams as code. Generates high-contrast, production-ready Mermaid architecture diagrams, workflows, and C4 models saved directly in docs/architecture/.
• obsidian: Obsidian vault operations. Runs the Obsidian CLI (read/create/search/manage notes, tasks, properties), builds Bases (.base views/filters/formulas), writes Obsidian Flavored Markdown (wikilinks, embeds, callouts), and develops/debugs plugins and themes.

🔗 MCP Integrations

Configuring, authenticating, and using external MCP servers across all supported agent platforms.

• composio-mcp: Connects AI agents to 1000+ external apps (Gmail, GitHub, Slack, Notion, Linear, Jira) via Composio. CLI-first path (ak_* project key) with MCP fallback (ck_* consumer key via x-consumer-api-key header). Includes multi-platform setup script (handles serverUrl vs url, mcp vs mcpServers, environment vs env across Claude Code/Desktop, Cursor, Devin CLI/Desktop, OpenCode, Antigravity IDE/CLI, OpenClaw), verify script, per-platform config reference, and cross-platform quirks matrix.
• notebooklm-mcp: Google NotebookLM (Gemini Notebook) integration via the nlm CLI and notebooklm-mcp server. Desktop nlm login is the default auth path; headless fallbacks (OpenClaw CDP or user-provided manual cookies.txt) require explicit user approval. Credentials/cookies are never logged, copied, or forwarded. Multi-platform setup script covering all 8 supported agent platforms, plus verify, auth guide, per-platform config reference, and cross-platform quirks matrix.
• wordpress-mcp: Expose WordPress to AI agents over MCP using pinned, verified plugins. Three paths: (A) wordpress/mcp-adapter official plugin from GitHub releases, (B) AI Engine plugin from wordpress.org, and (C) wp-mcp-ultimate (community, opt-in, requires explicit source review and user approval). High-privilege actions require explicit approval; WordPress posts/comments/user submissions are treated as untrusted data. Includes hardened WP-CLI install scripts with checksum support, Application Password / Bearer Token / OAuth setup, per-platform MCP config, endpoint verification, and troubleshooting.

📚 Documentation: each skill has a dedicated doc page in docs/en/ (English) and docs/pt-br/ (Português).

🛡️ Security Audits

Latest results from the skills.sh third-party audit (Gen Agent Trust Hub, Socket, Snyk). Click View to see the full report for a skill.

Updated: 2026-10-08

Mitigations applied (PR #11): notebooklm-mcp, orchestrator, and wordpress-mcp were hardened with explicit-approval gates, pinned installs, credential isolation, untrusted-content handling, and audit logging. The latest scan still flags architecture, notebooklm-mcp, and wordpress-mcp as 🟡 medium risk on Gen Agent Trust Hub, and notebooklm-mcp and sonarqube-autofix each carry 1 Socket alert.

Skill	Gen Agent Trust Hub	Socket alerts	Snyk	Details
architecture	🟡 medium	0	🟢 low	View
building-mcp-servers	✅ safe	0	🟢 low	View
code-review-and-quality	✅ safe	0	🟡 medium	View
composio-mcp	✅ safe	0	🟡 medium	View
create-agent-harness	✅ safe	0	🟢 low	View
create-issues	✅ safe	0	🟡 medium	View
create-readme	✅ safe	0	🟢 low	View
design	✅ safe	0	🟢 low	View
diagnose	✅ safe	0	🟢 low	View
drawio-architecture	✅ safe	0	🟢 low	View
execute-specs	✅ safe	0	🟢 low	View
gap-analysis	✅ safe	0	🟡 medium	View
improve-codebase-architecture	✅ safe	0	🟢 low	View
mermaid-architecture	✅ safe	0	🟢 low	View
migration-planner	✅ safe	0	⚪ pending	View
notebooklm-mcp	🟡 medium	1	🟢 low	View
observability-and-instrumentation	✅ safe	0	🟢 low	View
obsidian	✅ safe	0	🟢 low	View
orchestrator	✅ safe	0	🟡 medium	View
qa-analyst	✅ safe	0	🟡 medium	View
quality-test-implementation	✅ safe	0	🟢 low	View
reverse-engineer	⚪ pending	0	⚪ pending	View
scaffold-mvp	✅ safe	0	🟢 low	View
sonarqube-autofix	✅ safe	1	🟡 medium	View
web-design-guidelines	✅ safe	0	⚪ pending	View
wordpress-mcp	🟡 medium	0	🟡 medium	View
write-specs	✅ safe	0	🟢 low	View

---

📦 Installation

⚡ via skills.sh (Recommended)

The fastest way to install and auto-detect your environment.

npx skills add afonsoft/skills

🧩 via Claude Code plugin

Installs skills and slash commands natively (no install.sh needed):

/plugin marketplace add afonsoft/skills
/plugin install spec-driven@afonsoft

Commands are namespaced by the plugin name: /spec-driven:orchestrator and /spec-driven:<skill> for each skill.

🤖 via Codex plugin marketplace

The repo ships a Codex plugin manifest (.codex-plugin/plugin.json) and a repo marketplace catalog (.agents/plugins/marketplace.json):

codex plugin marketplace add afonsoft/skills

Then install spec-driven from the Plugins Directory, or invoke skills directly with $<skill> — Codex discovers them from the bundled skills/ directory. Skills are also discovered from .agents/skills/ (repo scope) and ~/.agents/skills/ (user scope, via install.sh --codex).

🌐 via OpenCode HTTP catalog

Add the catalog URL to any opencode.json — OpenCode downloads skills/index.json and refreshes each skill automatically when its version changes:

{
  "$schema": "https://opencode.ai/config.json",
  "skills": ["https://raw.githubusercontent.com/afonsoft/skills/main/skills/"]
}

Regenerate the catalog after skill changes with python3 scripts/build-opencode-catalog.py. OpenCode also discovers skills from .opencode/skills/, .claude/skills/, and .agents/skills/ in project scope.

🖥️ via install.sh (local clone)

Copies the skills into each IDE's skills directory and generates slash commands:

./install.sh --all        # all supported IDEs/CLIs + slash commands
./install.sh --claude     # Claude Code only
./install.sh --opencode   # OpenCode only
./install.sh --devin      # Devin Desktop + Devin CLI
./install.sh --cursor     # Cursor only
./install.sh --codex      # OpenAI Codex CLI only
./install.sh --agy        # Google Antigravity CLI only
./install.sh --aider      # Aider only
./install.sh --cline      # Cline only
./install.sh --continue   # Continue only
./install.sh --grok       # Grok CLI only
./install.sh --kimi       # Kimi Code CLI only
./install.sh --kiro       # Kiro CLI only
./install.sh --qwen       # Qwen Code only
./install.sh --dry-run    # preview without changing anything

Slash commands follow each CLI's own convention — some clients do not accept : in command names:

CLI	Invocation	Mechanism
Claude Code, OpenCode, Devin Desktop	/spec-driven and /spec-driven:<skill>	commands/spec-driven:<skill>.md shims
Devin CLI	/<skill>	skills are native slash commands — no shims needed; installed to ~/.config/devin/skills/
Qwen Code	/spec-driven and /spec-driven:<skill>	commands/spec-driven/<skill>.md (namespace via subdirectory)
Codex CLI	/prompts:spec-driven-<skill>	prompts/spec-driven-<skill>.md (custom prompts are deprecated — prefer $<skill>//skills)
Cline	/spec-driven-<skill>	~/.cline/data/workflows/ workflows
Continue	/spec-driven-<skill>	~/.continue/prompts/ with invokable: true
Grok CLI	/spec-driven-<skill>	~/.agents/commands/ (skills also appear as /<skill>)
agy, Kimi, Kiro	/<skill> (Kimi: /skill:<skill>)	skills are native slash commands — no shims needed
Aider	/read ~/.aider/skills/<skill>/SKILL.md	no file-based commands; an index is written to ~/.aider/spec-driven-skills.md

Reinstalling removes legacy /architecture:<skill> shims automatically.

📣 Publish on Skill Directories

SkillsLLM

SkillsLLM indexes open-source skills for Claude Code, Codex CLI, and ChatGPT. The scraper discovers repos daily via GitHub topics (claude-code, ai-agent, mcp-server, agent-skills, skill-md) and SKILL.md files. To list this collection:

1. Sign in with GitHub at Submit a Skill
2. Submit the repository URL: https://github.com/afonsoft/skills
3. The scraper validates, fetches metadata, runs a security scan (Semgrep + npm audit + pip-audit), and adds it to the catalog within 24 hours

Note: SkillsLLM's automated discovery filters for repos with 100+ stars. Manual submission via the form above bypasses that filter — the repo is then scanned and listed regardless of star count. The GitHub topics and description are already set so the scraper can categorize the skills correctly.

Awesome Skills

Awesome Skills discovers open-source SKILL.md skills from GitHub via its Awesome List Import. Each skills/<name>/SKILL.md directory becomes a separate listing with slug afonsoft-skills-<name>. Submit the repository URL through the site's Submit a Skill form:

• Repository URL: https://github.com/afonsoft/skills
• Branch: main
• Skills Path: /skills

Each skill's description frontmatter includes afonsoft so the collection is discoverable at awesomeskill.ai/search?q=afonsoft. The Awesome Skills search API matches against skill name and description only (not owner, repo, or tags), so the afonsoft attribution in each description is what makes the search return results.

SkillHub

SkillHub aggregates skills from GitHub sources. Open Sources → Add Source, then use:

• Name: afonsoft/skills
• Repository URL: https://github.com/afonsoft/skills
• Source Type: GitHub Repo
• Branch: main
• Skills Path: /skills

SkillHub imports the collection from this source and lists each valid SKILL.md directory in its marketplace.

LobeHub Skills Marketplace

LobeHub is the world's largest skills marketplace (100,000+ skills). Publishing is CLI-driven (no web form). Each skill gets identifier afonsoft-skills-<name>.

One-time setup (per machine, requires Node.js >= 22):

npx -y @lobehub/market-cli login           # browser OAuth
npx -y @lobehub/market-cli github connect  # verify GitHub ownership

Publish all skills locally:

./publish-lobehub.sh          # publishes all skills
./publish-lobehub.sh --dry-run # preview without publishing

Publish a single skill:

npx -y @lobehub/market-cli skill publish --dir skills/<skill-name> --identifier afonsoft-skills-<skill-name>

Automatic publishing via GitHub Actions:

A workflow (.github/workflows/lobehub-publish.yml) publishes all skills when a v* tag is pushed, a release is published, or when triggered manually (workflow_dispatch). To enable it, add two repository secrets:

1. LOBEHUB_M2M_CREDENTIALS — contents of ~/.lobehub-market/credentials.json (device registration)
2. LOBEHUB_USER_CREDENTIALS — contents of ~/.lobehub-market/user-credentials.json (OAuth tokens)

# After running lhm login + lhm github connect locally:
gh secret set LOBEHUB_M2M_CREDENTIALS < ~/.lobehub-market/credentials.json
gh secret set LOBEHUB_USER_CREDENTIALS < ~/.lobehub-market/user-credentials.json

The workflow restores both credential files, verifies auth, then runs ./publish-lobehub.sh. The refresh token auto-renews the access token, so the workflow stays authenticated across runs.

After publishing, skills appear at market.lobehub.com/s/skills/afonsoft-skills-<name> and are searchable at lobehub.com/skills?q=afonsoft.

ClawHub

ClawHub is the public skill registry for OpenClaw. Each skills/<name>/SKILL.md directory becomes a versioned, installable skill under the afonsoft publisher.

Install from ClawHub:

# Search for a skill
clawhub search "afonsoft"

# Install one skill
clawhub install @afonsoft/<skill-name>

# Or install with OpenClaw directly
openclaw skills install @afonsoft/<skill-name>

Publish all skills locally:

npm i -g clawhub
clawhub login
./publish-clawhub.sh          # publish new/changed skills
./publish-clawhub.sh --dry-run # preview the publish plan

The clawhub CLI uses clawhub sync to compare local fingerprints against the registry and publishes only new or changed skills, defaulting to the next patch version.

Automatic publishing via GitHub Actions:

A workflow (.github/workflows/clawhub-publish.yml) publishes all skills when a v* tag is pushed, a release is published, or when triggered manually (workflow_dispatch). To enable it, add the repository secret:

1. CLAWHUB_TOKEN — your ClawHub publisher token (clawhub token create or from https://clawhub.ai/settings/tokens)

gh secret set CLAWHUB_TOKEN

📖 How to use

1. Install the collection using one of the methods above. Running ./install.sh additionally generates /spec-driven:<skill> (or /spec-driven-<skill> where : is not supported) slash commands for the supported CLIs — see the table above.
2. Start with the orchestrator — /spec-driven (same as /spec-driven:orchestrator) or "use the orchestrator skill" — and let it drive the spec → issues → slices → QA → PR pipeline.
3. Invoke an individual skill directly when you know exactly what you need (e.g., /spec-driven:write-specs, or "Use the create-agent-harness skill to setup this repo"). The agent loads the SKILL.md and follows the structured workflow.

⚖️ License

MIT - See LICENSE.

🛠️ Skill Development Tools

skillxp

skillxp observes skill loading behavior across harnesses (Claude Code, Codex CLI, Antigravity). Stage a skill in a fresh fixture, invoke the harness headlessly, and see what actually reached the model with transcript evidence. Install via brew install agent-ecosystem/tap/skillxp or npm install -g skillxp. Use skillxp harnesses to list supported platforms and skillxp observe -harness <name> -install ./my-skill ... to trace skill activation and phrase loading.

📊 Skills Catalog

Browse all available skills at skills.sh.

---

Star History

StarMapper

StarMapper also requires a GitHub token to fetch star geolocation data. The live map image is not available until the repository is scanned.