Skip to content

README.md

Latest commit

 

History

History
203 lines (151 loc) · 5.76 KB

README.md

File metadata and controls

203 lines (151 loc) · 5.76 KB
Raw

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