Skip to content

chore: adopt AI-native SDLC, risk-tiered review and changie - #132

Draft
goanpeca wants to merge 1 commit into
mainfrom
chore/adopt-ai-native-sdlc
Draft

goanpeca wants to merge 1 commit into
mainfrom
chore/adopt-ai-native-sdlc

Conversation

@goanpeca

Copy link
Copy Markdown
Contributor

What

Adopts the AI-native SDLC playbook on this repo, adapted to a small Astro site, plus the review practices from "Solving code review at Anthropic". Closes #131.

Changes

  • AGENTS.md is the canonical agent and contributor guide (commands, CI and the Dependabot guard, generated data, how changes flow, things agents get wrong, verifying, opening a PR); CLAUDE.md imports it.
  • REVIEW.md: what failure looks like here, risk tiers set by the change (Low, Medium, High, with always-human paths), passes including a Security pass, paths to skip, severity (Important, Nit capped at five, Pre-existing), file:line evidence, a convergence rule (diff-only from round 3, three-round cap, no repeats), every finding answered, and a count-first summary.
  • docs/SDLC.md: when the intent, spec, plan chain applies, the seven review layers, one-step rollback, "which layer should have caught it", measuring, and norms. docs/review-lessons.md holds recurring findings and a "Known misses" eval set.
  • intent/ templates and intent/review-process/intent.md (the tiered-review proposal for Adopt the AI-native SDLC playbook, changie changelog and review process #131).
  • .claude/: the playbook skills, a fresh-context read-only reviewer agent, a PostToolUse hook that runs Biome on edited files, and a PreToolUse hook that asks before editing generated data, workflows, release and hook files.
  • changie 1.24.0 (cross-repo standard): .changie.yaml, .changes/, CHANGELOG.md, RELEASE.md, npm run changelog, changelog:batch, changelog:merge, and changelog.yml (with the two-clause Dependabot guard and a skip-changelog label bypass) running scripts/check-changelog.mjs.
  • npm run ci (checks, then build) mirrors ci.yml; npm run review:metrics reports human approvals and comments per PR, AI review rounds, time to first human review, and reverts.
  • PR template gains Testing, Risk and How to revert; CODEOWNERS covers the High-tier paths; CONTRIBUTING.md checklist updated.

Testing

npm run ci passes locally (lint, format, typecheck, validate, docs lint, spellcheck, build). node scripts/check-changelog.mjs reports the fragment as present. A scratch changie batch auto plus changie merge produces a CHANGELOG.md that passes markdownlint. npm run review:metrics -- --limit 30 runs against this repo.

Risk

High per the new tiers (touches .github/, scripts/, .claude/, package.json). No site code or data changes; the deploy path is untouched.

How to revert

Revert this commit. Nothing outside the repo was changed.

Needs a maintainer (settings, not files)

  • Enable an AI reviewer on PRs (Claude Code Review at Quick or Standard, or Copilot review) and an automated security review.
  • Branch protection on main: require code-owner review, require the checks and changelog checks, require conversation resolution, dismiss stale approvals on new commits, require branches to be up to date.
  • Create the skip-changelog label.
  • No merge queue, feature flags, staged releases or nightly review agents at this volume; listed as open questions in the intent.

Signed-off-by: Gonzalo Peña-Castellanos <goanpeca@gmail.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The required changelog check succeeds when fetching or diffing fails, allowing source changes without changelog fragments to bypass enforcement.

6 open issues
What changed in this PR

6 Important, 2 Nit, 0 Pre-existing. Risk: High. Checked the supplied changes against #131 and the repository review guidance, with focused inspection of package scripts and available skills. No tests or builds were run.

This PR introduces a documented development and review process for the Astro catalog site, plus changelog tooling and local agent hooks. Site code, catalog data and deployment behavior remain unchanged.

Changes:

  • Establishes shared contributor guidance, risk-tiered review, and intent/spec/plan templates.
  • Adds agent skills, a reviewer agent, and edit-time checks.
  • Introduces changie, a PR changelog check, a combined CI command, and review metrics.
File Description
scripts/​review-metrics.mjs Reports approval, review and revert metrics.
scripts/​check-changelog.mjs Checks source changes for changelog fragments.
REVIEW.md Defines review passes, risk tiers and evidence standards.
RELEASE.md Documents changelog assembly and deployment.
package.json Adds changie and development-process commands.
package-lock.json Locks the changie dependency.
intent/​review-process/​intent.md Records the draft risk-tiered review proposal.
intent/​README.md Provides intent, spec and plan templates.
docs/​SDLC.md Describes the development lifecycle and review layers.
docs/​review-lessons.md Records recurring mistakes and future regression examples.
CONTRIBUTING.md Updates the PR checklist.
CLAUDE.md Imports the canonical agent guidance.
CHANGELOG.md Introduces the changelog header.
AGENTS.md Centralizes contributor and agent guidance.
.github/​workflows/​changelog.yml Adds the changelog job with exemption guards.
.github/​PULL_REQUEST_TEMPLATE.md Adds testing evidence, risk and rollback prompts.
.github/​CODEOWNERS Assigns maintainers to policy-critical paths.
.cspell/​project-words.txt Adds terminology used by the new documentation.
.claude/​skills/​sdlc-subagents/​SKILL.md Guides parallel sessions and scoped subagents.
.claude/​skills/​sdlc-spec/​SKILL.md Guides requirements and design documentation.
.claude/​skills/​sdlc-pr-review/​SKILL.md Defines structured review and feedback practices.
.claude/​skills/​sdlc-policy-skill/​SKILL.md Guides policy skills and enforcement checks.
.claude/​skills/​sdlc-plan/​SKILL.md Guides implementation planning and verification criteria.
.claude/​skills/​sdlc-intent/​SKILL.md Guides problem and outcome capture.
.claude/​skills/​sdlc-hook-gate/​SKILL.md Documents approval-hook patterns.
.claude/​skills/​sdlc-hook-gate/​assets/​gate-template.sh Supplies a release approval-gate template.
.claude/​skills/​sdlc-feedback-loop/​SKILL.md Guides verification and test protection.
.claude/​skills/​sdlc-claude-md/​SKILL.md Guides maintenance of agent context.
.claude/​skills/​ai-native-sdlc/​SKILL.md Routes work through lifecycle stages.
.claude/​settings.json Registers pre-edit and post-edit hooks.
.claude/​hooks/​protected-paths.mjs Requests approval for protected file edits.
.claude/​hooks/​biome-check.mjs Runs Biome after supported file edits.
.claude/​agents/​reviewer.md Defines a fresh-context reviewer agent.
.changie.yaml Configures changelog categories and formatting.
.changes/​unreleased/​Added-20261027-120000.yaml Records the process adoption as a fragment.
.changes/​unreleased/​.gitkeep Preserves the unreleased-fragment directory.
.changes/​header.tpl.md Supplies the generated changelog header.

Review effort: Balanced

Comment on lines +16 to +17
console.log("Could not diff against base; skipping changelog check.");
process.exit(0);
Comment on lines +6 to +14
import { readFileSync } from "node:fs";

let file;
try {
file = JSON.parse(readFileSync(0, "utf8"))?.tool_input?.file_path || "";
} catch {
process.exit(0);
}
const rel = file.replace(/^.*\/backblaze-labs\/website\//, "");
# keep both the actor and PR-author clauses, or dependabot PRs start spending CI.

on:
pull_request:
process.exit(0);
}

const addedFragment = changed.some((f) => /^\.changes\/unreleased\/.+\.ya?ml$/.test(f));

const addedFragment = changed.some((f) => /^\.changes\/unreleased\/.+\.ya?ml$/.test(f));
const sourceChanged = changed.some(
(f) => /^(src|scripts|public|\.github\/workflows)\//.test(f) && !/^src\/data\/.*\.json$/.test(f),
Comment on lines +59 to +60
} while (after && prs.length < limit);
prs.splice(limit);

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt the AI-native SDLC playbook, changie changelog and review process

2 participants