| name | ai-sdlc-governance |
| description | AI-SDLC project governance rules, workflow expectations, and pre-commit checklist. Loaded automatically at session start. |
| autoContext | true |
AI-SDLC Governance Rules
Critical Rules — NEVER violate these
- NEVER merge any pull request. Do not run
gh pr merge, git merge into main, or any merge operation. Only create or update PRs. The human merges.
- Dismiss PR reviews only with documented reason. You may dismiss reviews when they failed due to infrastructure issues (e.g., API credit exhaustion) or when findings are documented false positives. Always include a clear explanation in the dismissal message. Prefer updating
.ai-sdlc/review-policy.md for recurring false positives.
- NEVER close issues or PRs. Do not run
gh pr close or gh issue close. The human decides what to close.
- NEVER force push. Do not run
git push --force or git push -f.
- NEVER delete branches. Do not run
git branch -D or git branch -d.
- NEVER run destructive git operations. No
git reset --hard, git checkout -- ., git restore ..
These rules are also enforced technically via .claude/hooks/enforce-blocked-actions.sh and .ai-sdlc/agent-role.yaml blockedActions.
Pre-Commit Checklist
Before EVERY commit, run these checks and fix any failures:
pnpm build
pnpm test
pnpm lint
pnpm format:check
Test File Check
Before committing new .ts modules, verify:
- Every new
src/**/*.ts file (not types.ts, index.ts) has tests somewhere
- Tests can be in a co-located
.test.ts file OR in another test file that imports it
- Run the relevant tests and confirm they pass before staging
Do NOT rely on CI to catch missing tests — check locally first.
Do NOT commit if any of these fail. Fix the errors first, then commit.
Git Flow
- Always rebase feature branches onto main. Never merge main into a feature branch.
- When updating a feature branch with latest main:
git fetch origin && git rebase origin/main
- After rebase with conflicts resolved:
git push --force-with-lease origin <branch>
- Never use
gh api pulls/N/update-branch with merge method.
- Keep commit history linear — no merge commits on feature branches.
- Use conventional commits:
feat:, fix:, test:, docs:, chore:, style:
Workflow Expectations
When given a multi-step task, complete ALL steps before stopping:
- Research the task by reading relevant files
- Plan the approach (use EnterPlanMode for non-trivial tasks)
- Implement the changes
- Run typecheck, tests, lint, format — fix any failures
- Commit with a conventional commit message
- Push to the branch
- Create a PR if needed (but do NOT merge)
- Report what was done and what remains
If blocked at any step, say which step you're stuck on and why.
PR Workflow
- Create PRs with descriptive titles and bodies
- After pushing, tell the user the PR is ready for their review
- If CI fails or reviews request changes, fix the issues and push again
- Use
/fix-pr <number> to automatically gather and fix PR issues
- NEVER merge — always wait for the human
Review Policy
When review agents post findings:
- APPROVE with suggestions/minors → PR is ready for human merge
- CHANGES_REQUESTED with critical/major → fix the real issues, push again
- False positives → update
.ai-sdlc/review-policy.md with better calibration, don't dismiss reviews
Project Structure
orchestrator/ — core pipeline logic (TypeScript)reference/ — framework reference implementationdogfood/ — CLI scripts that invoke the orchestrator.ai-sdlc/ — pipeline configuration (YAML) — agents cannot modify these files.claude/ — Claude Code hooks, commands, and skills.github/workflows/ — GitHub Actions — agents cannot modify these filesspec/schemas/ — JSON schemas for YAML validation
Testing
- Use Vitest for all orchestrator and reference tests
- Coverage target: 80% patch coverage on PRs
- Run
pnpm test from repo root for all packages
- Run
pnpm --filter @ai-sdlc/orchestrator test for orchestrator only
