efficiency-audit

sdlc-skills

The content layer for AI-assisted software delivery. Role-based agent personas (BA, Tech Lead, PM, devs, QA, PA), workflow skills (TDD, bugfix, code review, task completion, memory, …), and a registry that pulls proven skills from Matt Pocock, Jesse Vincent (obra/superpowers), and Paul Hudson so you don't have to reinvent them.

Install via the npx one-shot or a native plugin manifest and use the agents + skills directly in any AI IDE (Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, Windsurf, Codex).

Architecture

flowchart TB
    subgraph sdlc["sdlc-skills — content + install resolution"]
        direction TB
        agents[/"bundles/<br/>agent + skill content"/]
        skills[/"orphan skills/<br/>standalone-only content"/]
        registry[("skills.json<br/>catalog: orphan + external")]
        installer(["bin/init.mjs<br/>npx installer"])
        agents --- skills
        skills --- registry
        registry --- installer
    end

    subgraph consumers["consumers"]
        direction LR
        ides["AI IDEs<br/>Claude Code • Cursor<br/>Gemini CLI • Copilot CLI<br/>Windsurf"]
    end

    subgraph externals["upstream external skill sources"]
        direction LR
        ext_matt[["mattpocock/skills<br/>skills/engineering/tdd"]]
        ext_obra[["obra/superpowers<br/>brainstorming, debugging,<br/>verification, ..."]]
        ext_tws[["twostraws/*-Agent-Skill<br/>SwiftUI, SwiftData,<br/>Swift Testing, Concurrency"]]
        ext_msft[["microsoft/playwright-cli<br/>playwright-cli"]]
    end

    installer ==>|fetch at install time| ext_matt
    installer ==>|fetch at install time| ext_obra
    installer ==>|fetch at install time| ext_tws
    installer ==>|fetch at install time| ext_msft

    sdlc ==>|direct install via<br/>plugin manifest or npx| ides

(Node shapes convey grouping so colors aren't needed: / / parallelograms for content dirs, ( ) round-ended for the installer, cylinders for the registry, [[ ]] subroutines for external sources. GitHub's Mermaid renderer uses theme-adaptive colors in both light and dark mode.)

Agents are self-describing — each AGENT.md carries its own metadata (role, group, theme, aliases, skills, model). IDE plugin systems read it at install time. Nothing duplicated.

Most agents and skills live inside bundles (bundles/<id>/agents/ and bundles/<id>/skills/). The top-level agents/ and skills/ directories hold only standalone-only "orphan" content: one agent (personal-assistant) and eight skills (deep-research, gathering-context, verifying-outcomes, microsoft-365, obsidian-vault, tosca-automation, vividus, xray-testing). skills.json registers those orphan monorepo skills and the external skills fetched from upstream.

External skills (Matt Pocock's tdd, Jesse Vincent's brainstorming / systematic-debugging / etc., Paul Hudson's Swift skills) live in their upstream repos. The installer resolves each agent's declared skill list against skills.json, clones external repos on first install into ~/.cache/sdlc-skills/registry/, and copies the subdir into your project's skills directory (or symlinks it with --symlink).

What lands in your project

After npx … init + a scout run, your target project has two top-level directories plus the IDE's native install location:

your-project/
├── .claude/                  ← IDE-native install (or .cursor/, .windsurf/, .github/)
│   ├── agents/<role>/        agent config (AGENT.md + SOUL.md)
│   └── skills/<name>/        skill content (SKILL.md + references)
│
├── .agents/                  ← IDE-neutral content — every agent reads
│   ├── profile.md            scout output: project card
│   ├── architecture.md       scout output: system design
│   ├── conventions.md        scout output: coding standards
│   ├── testing.md            scout output: test infrastructure
│   ├── team-comms.md         scout output: transport + roster
│   ├── onboarding.md         scout's audit trail
│   └── memory/<role>/        memory-skill dir: MEMORY.md index,
│                             curated entries (incl. scout-seeded
│                             project_briefing.md), daily/, snapshot.md
│
├── AGENTS.md                 scout output: full team reference
└── CLAUDE.md                 scout output: 80-line auto-loaded context

.agents/ holds content every agent reads regardless of IDE. Nothing in .agents/ is host-specific — it works identically under Claude Code, Cursor, Gemini CLI, Copilot CLI, and Windsurf.

Scout (scout agent, run once when onboarding) populates everything under .agents/ plus AGENTS.md / CLAUDE.md at the root. Re-run scout whenever the stack evolves to refresh.

Install — pick one path

There are really two paths: the full experience (npx installer) and the monorepo-only fallbacks (native IDE plugins for people who don't want to be happy).