Oikos Pr

Oikos PR Creator

Ship code safely: lint → tests → branch → commit → push → PR. Never create a branch or commit until both lint and tests are green.

Step 0 — Understand what changed

Before anything else, run these three commands in parallel:

git status                          # what files changed
git diff HEAD                       # what the changes actually are
git log main..HEAD --oneline        # commits not yet on main (may be empty)

Use the output to:

• Know which files to stage
• Draft an accurate commit message
• Detect if you are already on a feature branch (don't create a second one)

Step 1 — Run lint

npx turbo run lint

This lints all workspaces (web, ui, types, config) with --max-warnings 0.

If lint passes

Continue to Step 2.

If lint fails

1. Attempt auto-fix for the web workspace (ESLint can fix ~30% of issues):

   cd apps/web && npx eslint . --ext ts,tsx --fix
   

2. Re-run the full lint:

   npx turbo run lint
   

3. If still failing, stop. Report the remaining errors clearly:
   • List each file and the exact error message
   • Explain why you cannot auto-fix it (e.g. logic errors, missing translations, wrong prop types)
   • Ask the user to fix the remaining errors, then invoke the skill again
   • Do NOT proceed to git operations

Step 2 — Run web unit tests

cd apps/web && npx vitest run

If tests pass

Continue to Step 3.

If tests fail

Stop. Report which test files failed and which specific assertions failed. Do not proceed to git operations until tests are green.

Skip this step only if the user explicitly says "skip tests" or "lint only".

Step 3 — Determine branch name

If the user provided a branch name in their request, use it exactly.

Otherwise, derive one from the nature of the changes:

Keep the slug short (≤ 5 words, kebab-case, no issue numbers unless provided).

Step 4 — Prepare the branch

If already on a feature branch (not main or develop)

Skip branch creation — commit directly to the current branch.

If on main or develop

git checkout main
git pull origin main
git checkout -b <branch-name>

Step 5 — Stage and commit

Stage only the files relevant to this change. Prefer explicit file lists over git add -A — avoid accidentally staging .env, *.json lock file noise, or unrelated work-in-progress files.

git add <file1> <file2> ...

Commit message format (Conventional Commits):

<type>(<scope>): <short summary in present tense>

<optional body — what and why, not how>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Rules:

• Type: feat, fix, test, ci, docs, refactor, chore
• Scope: the feature area, e.g. e2e, calendar, auth, ci
• Summary: ≤ 72 characters, imperative mood ("add", "fix", "remove" — not "added")
• Body: include only if the why isn't obvious from the summary
• Always include the Co-Authored-By trailer

Use a heredoc to avoid shell quoting issues:

git commit -m "$(cat <<'EOF'
feat(e2e): add active-curriculums Playwright spec

Implements §6 of the E2E testing plan. Seeds two active and one
archived curriculum, then asserts the dashboard widget shows only
the active ones and that the row count matches the live API.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
EOF
)"

Step 6 — Push

git push -u origin <branch-name>

Step 7 — Open the PR

gh pr create \
  --title "<type>(<scope>): <same summary as commit>" \
  --body "$(cat <<'EOF'
## What changed
<!-- 2-4 bullet points describing the changes -->

## Why
<!-- The motivation: bug fix, new feature, CI requirement, etc. -->

## Test plan
- [ ] `npx turbo run lint` passes (run by skill before creating this PR)
- [ ] `cd apps/web && npx vitest run` passes (run by skill before creating this PR)
- [ ] Manually tested in browser / Docker stack (if applicable)

## Related
<!-- Link to issues, plan docs, or prior PRs if relevant -->

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
EOF
)"

PR title must match the commit subject line exactly.

Guardrails — never do these

• Never skip lint or tests to save time. If they fail, stop and report.
• Never force-push to main or develop.
• Never use git add -A or git add . without reviewing what would be staged.
• Never commit .env files, *.local, or anything matching .gitignore.
• Never amend the previous commit when a pre-commit hook fails — create a new commit.
• Never bypass hooks with --no-verify.
• Never open a draft PR without telling the user — ask first if unsure.

Error reporting format

When stopping due to lint or test failures, always output:

🚫 Cannot create PR — <lint|tests> failed.

Errors:
  <file>:<line>  <rule>  <message>
  ...

Auto-fix was <attempted and reduced X errors / not applicable>.
Please fix the remaining errors and run the skill again.

Source: oikos-family-education/oikos-web — distributed by TomeVault.