architecture

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\]

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.

💎 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. Inte