AI SDLC Claude Harness

Claude Code skills for onboarding Claude to brownfield projects and keeping its work aligned with a team's SDLC habits.

This repository contains reusable Claude Code skills plus the project notes used to evolve them. The skills are language-agnostic: they inspect the target project, derive conventions from evidence, and write context artifacts into that project.

What It Is

The harness is a set of invokable Claude Code workflows. The core workflow onboards a project, reviews completed implementation work, captures story-level retros, and graduates repeated learnings into shared project context.

Skill	When to invoke	Who invokes it
onboard	Once for an existing project	Team lead
after-coding	After implementation, before raising a PR	Engineer
retro	Immediately after after-coding	Engineer
graduate-retros	After several stories, before a release, or when retros accumulate	Team lead

The repository also includes supporting skills. Thanks to Matt Pocock for providing the skills below. Ref: https://github.com/mattpocock/skills.

Skill	Purpose
to-issues	Break a plan, spec, or PRD into independently grabbable tracer-bullet issues
tdd	Guide implementation through a red-green-refactor loop using behavior-focused tests
grill-with-docs	Stress-test a plan against project terminology and capture domain decisions in docs

Repository Layout

skills/
  onboard/
  after-coding/
  retro/
  graduate-retros/
  to-issues/
  tdd/
  grill-with-docs/

issues/
requirements/
CONTEXT.md
README.md

• skills/ contains the active Claude Code skills.
• skills/onboard/ includes the evidence collection protocol, artifact formats, dimension-agent prompts, and ast-grep query library.
• skills/tdd/ contains supporting guidance for tests, mocking, interface design, deep modules, and refactoring.
• skills/grill-with-docs/ contains the glossary and ADR formats used while sharpening domain decisions.
• CONTEXT.md records project glossary and design decisions for this harness.
• issues/ and requirements/ preserve completed and current development notes.

Installation

Clone this repo and copy the skill directories into your Claude Code skills directory:

git clone <this-repo-url>
mkdir -p ~/.claude/skills
cp -R ai-sdlc/skills/* ~/.claude/skills/

Skills are installed per engineer. The artifacts they produce, such as CLAUDE.md and context/, live in the project repo where the skills are run and should be reviewed and committed with the code.

Usage

Onboard Claude to a Project

Run this once from the target project root:

/onboard

The skill detects the stack, collects code evidence, resolves genuine convention conflicts with the team lead, analyzes key project dimensions, and writes shared context artifacts.

For a single-repo project it produces:

• CLAUDE.md
• context/onboard-report.md
• context/conventions.md
• context/decisions.md

For a monorepo it also writes one service-specific CLAUDE.md per detected component.

If ast-grep is installed, onboard can use structural sg --json queries for Go, TypeScript, JavaScript, Python, and Java pattern extraction. If it is missing, the skill prints install guidance and falls back to reading representative files.

Review Completed Implementation

/after-coding

Run this after code is written and tests pass. The skill expects a matching feature directory with context/features/<feature-name>/implementation-guide.md, reviews the actual diff against project rules, checks deviations from the plan, and writes:

context/features/<feature-name>/execution-report.md

BLOCK findings must be fixed before raising a PR. FLAG findings are advisory.

Capture a Story Retro

/retro

Run immediately after after-coding. The skill asks what Claude got wrong, what prompting worked, and what was missing from the briefing. It writes a pending retro draft:

context/features/<feature-name>/retro.md

Engineers do not write directly to CLAUDE.md from retros.

Graduate Accumulated Retros

/graduate-retros

The team lead runs this after several stories or before a release. The skill reads pending retro drafts, clusters repeated learnings, proposes additions to CLAUDE.md, context/conventions.md, or context/prompt-templates.md, and only writes approved changes.

Break Plans into Issues

/to-issues

Use this when a plan, spec, or PRD needs to become implementation tickets. The skill drafts thin vertical slices, asks the user to confirm granularity and dependencies, then publishes approved issues to the issue tracker.

Work Test-First

/tdd

Use this when building a feature or fixing a bug with test-driven development. The skill keeps the loop vertical: one behavior test, one minimal implementation, then the next behavior.

Stress-Test a Plan with Docs

/grill-with-docs

Use this when a plan needs sharper domain language or decision pressure. The skill checks the plan against existing CONTEXT.md and ADRs, asks one question at a time, and updates documentation inline as terms and decisions crystallize.

Generated Artifact Structure

A typical onboarded project ends up with:

CLAUDE.md
context/
  onboard-report.md
  conventions.md
  decisions.md
  features/
    <feature-name>/
      design.md
      implementation-guide.md
      execution-report.md
      retro.md
  prompt-templates.md

Monorepos may also have service-level CLAUDE.md files beside each component.

Dependencies

• Claude Code with skills support
• ast-grep (sg) is optional but recommended for faster structural pattern extraction during onboarding