commit cd3efb9dfe877302acc6f0d0124b0d934aac5353 Author: rafael Date: Tue Oct 13 22:23:11 2026 +0800 Initial commit: global opencode configuration diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..0e7bbbb --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "skills/simplified-technical-english"] + path = skills/simplified-technical-english + url = https://github.com/0xpili/simplified-technical-english.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7512fdf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# AGENTS.md + +## What this repository is + +This is the user's **global opencode configuration directory** +(`~/.config/opencode`). It holds the settings, custom agents, and skills that +opencode loads for every session on this machine. It is not an application +codebase — there is no build, test, or lint step. The "source" is the config +itself, and the way to verify a change is to confirm the config still loads +(restart opencode). + +## Layout + +``` +opencode.jsonc Global config: providers, MCP servers, skills path, shell +agent/ Custom agent definitions (markdown + frontmatter) + assistant.md Read-only code Q&A primary agent +skills/ Custom skills, one folder per skill (each has SKILL.md) + change-code-review/ Review only the last set of changes + incremental-implementation/ Deliver changes in thin, verifiable slices + repo-code-review/ Review the repo in its current state + resume-coach/ Recruiter-style resume review/rewrite + simplified-technical-english/ ASD-STE100 controlled-language writing +package.json Declares @opencode-ai/plugin (pinned version) +``` + +`node_modules/`, `package.json`, `package-lock.json`, `bun.lock`, and +`.gitignore` are listed in `.gitignore` and are intentionally **not** tracked. + +## Editing config (`opencode.jsonc`) + +- Keep `"$schema": "https://opencode.ai/config.json"` at the top. +- The schema at that URL is the source of truth. Fetch and read it before + writing any field not already present; opencode **hard-fails on invalid + config**, so a wrong shape breaks startup. +- `skills.paths` is an object with a `paths` array, not a bare array. +- Config is loaded once at startup and is **not hot-reloaded**. After changing + any config, agent, skill, or plugin file, tell the user to quit and restart + opencode. +- Never commit secrets. Provider keys and MCP tokens should use `{env:VAR}` + interpolation rather than literals. + +## Adding or editing agents + +- File form: `agent/.md`. The markdown body is the prompt; do not also + put `prompt:` in the frontmatter. +- Allowed frontmatter fields: `name, model, variant, description, mode, hidden, + color, steps, options, permission, disable, temperature, top_p`. +- `mode` is one of `primary`, `subagent`, `all`. +- Permissions: `permission` accepts an action string or an object keyed by tool. + Within an object the **last matching pattern wins**, so put broad rules first + and narrow rules last. + +## Adding or editing skills + +- One folder per skill: `skills//SKILL.md` (filename exactly `SKILL.md`). +- Required frontmatter: `name` (lowercase-hyphenated, matches the folder) and a + `description` that states both **what** the skill does and **when** to trigger + it, front-loading concrete keywords. Skills without a description are filtered + out and never surfaced. +- Optional frontmatter: `license`, `compatibility`, `metadata`. +- Put long reference material in sibling files (e.g. `references/`, + `examples/`) and point to them from the body instead of inlining everything. + +## Style + +- Markdown. Keep files focused and avoid redundancy. +- Do not add comments or content the user did not ask for. diff --git a/agent/assistant.md b/agent/assistant.md new file mode 100644 index 0000000..ca67f7e --- /dev/null +++ b/agent/assistant.md @@ -0,0 +1,55 @@ +--- +description: Read-only code Q&A. Ask questions about your code, language syntax, libraries/packages, or how to accomplish a task with a given library, and get explanations and suggestions without any edits. Use for "what does this do", "why is this written this way", "how does X work", "what's the syntax for Y", "does library Z support this?", or "how do I achieve X with framework Y?". +mode: primary +permission: + edit: deny + bash: + "*": "deny" + "git log*": "allow" + "git blame*": "allow" + "git show*": "allow" + "git diff*": "allow" + "git status*": "allow" + task: allow + todowrite: deny + webfetch: allow + websearch: allow +--- + +You are a code Q&A assistant, not an agent that performs work. The user asks questions — about their code, about syntax, about libraries and packages, or about how to accomplish tasks — and you answer. You never modify anything. + +## Hard rules + +- Never create, edit, or delete files — including scratch or example files. You cannot, and must not attempt to. +- Never run shell commands except read-only git queries (`git log`, `git blame`, `git show`, `git diff`, `git status`) used to answer historical "why is this like this?" questions. +- Use read, glob, and grep to inspect code. For a wide codebase search ("where is X handled?", "what calls this?"), delegate to the explore subagent instead of scanning manually. +- Do not use todo lists, plans, or multi-step task workflows. Answer the question; that is the whole job. + +## Kinds of questions + +**This repository's code** ("what does this do", "why is it written this way", "any issues here?") +- Read the relevant code first; never answer from assumption. Use git history/blame when the answer likely lives there (intent, bug fixes, migrations) and cite the commit. + +**General syntax and language semantics** ("what's the syntax for…", "how does this operator/keyword/collection behave?") +- Answer directly from knowledge with a small, self-contained example. No need to read the codebase unless the question ties back to it. Do not water down the answer with project-specific caveats that weren't asked for. + +**Libraries, packages, and frameworks** ("does X support Y?", "how do I achieve Z with this library?") +- If the library is used in this project, first check the manifest/lockfile (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, etc.) and any vendored/installed sources, and answer for the pinned version — APIs change between versions; say which version your answer applies to. +- Prefer grounding in the installed package's actual source, types, or bundled docs when present (read/glob/grep, or explore subagent). +- When uncertain, version-specific, or possibly newer than your knowledge, verify against official documentation with webfetch/websearch and cite the doc URL. Never present a guess as fact — state confidence explicitly. +- For "how do I achieve X" answers, give the idiomatic approach for that library, with a short code example as a fenced snippet. Suggest, never apply: the user can switch to the build agent if they want it actually implemented. + +## How to answer + +1. Answer the question that was actually asked, first and directly. No preamble like "Let me look at that" — just the answer. +2. Scope to what was asked. If the user points at a function, file, or snippet, answer about that. Do not broaden into the rest of the codebase unless needed for correctness of the answer. +3. Cite evidence: repo code as `path/to/file.ts:123` (or line ranges), external knowledge as documentation URLs. Quote the few relevant lines rather than whole files. +4. Explain in layers: short direct answer first, then deeper mechanics or context only if the question implies it. +5. For "any issues / suggestions / how would you improve this" questions: give concrete suggestions as fenced code snippets or prose proposals that are NOT applied. End with a one-line note that the user can switch to the build agent if they want a change actually made. Never offer to "go ahead and apply it" — you can't. +6. If the question is ambiguous and the answer materially differs by interpretation, ask one short clarifying question instead of guessing. + +## Style + +- Concise and direct; a short paragraph or a few bullets beats an essay. Match the size of the question. +- When explaining the user's own code, use the codebase's actual names and idioms. For syntax and library questions, be as complete as the question requires. +- Markdown formatting, code fences for snippets, `file:line` for repo references. diff --git a/opencode.jsonc b/opencode.jsonc new file mode 100644 index 0000000..22c20a1 --- /dev/null +++ b/opencode.jsonc @@ -0,0 +1,42 @@ +{ + "$schema": "https://opencode.ai/config.json", + "skills": { + "paths": ["/C:/Users/rsfor/.config/opencode/skills"] + }, + "provider": { + "lm-studio": { + "name": "LM Studio", + "npm": "@ai-sdk/openai-compatible", + "options": { + "baseURL": "http://127.0.0.1:18201/v1" + }, + "models": { + "ornith-1.5-9b": { + "name": "Ornith 1.5 9B (local)", + "modalities": { + "input": ["text", "image"], + "output": ["text"] + }, + "limit": { + "context": 65536, + "output": 32768 + } + } + } + } + }, + "mcp": { + "tavily": { + "type": "remote", + "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=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", + "enabled": false + } + }, + "tools": { + "tavily_tavily_crawl": false, + "tavily_tavily_map": false, + "tavily_tavily_research": false + }, + "disabled_providers": [], + "shell": "cmd" +} \ No newline at end of file diff --git a/skills/change-code-review/SKILL.md b/skills/change-code-review/SKILL.md new file mode 100644 index 0000000..beab5f4 --- /dev/null +++ b/skills/change-code-review/SKILL.md @@ -0,0 +1,91 @@ +--- +name: change-code-review +description: Review only the last set of changes (staged + unstaged, else the most recent commit) for bugs, security issues, and guidance-doc (AGENTS.md/CLAUDE.md) compliance. Use when asked to review my changes, review the diff, or check staged/uncommitted work before committing. +--- + +# Change Code Review + +Provide a rigorous, structured code review of the **last set of changes** only. Follow these steps precisely: + +## 1. Resolve the change set +Use git via Bash to determine the last set of changes, in this priority order: +1. Staged and unstaged working-tree changes combined: `git status --porcelain`, `git diff`, `git diff --staged`. +2. If the working tree is clean, the most recent commit: `git show --stat HEAD` and `git diff HEAD~1 HEAD` (handle a root commit where `HEAD~1` does not exist). +3. If neither exists, report "No changes to review" and stop. + +Record the diff, the changed files, and the changed line ranges. This is the only scope for the rest of the review. + +## 2. Eligibility check +Skip (report "No review needed") if any apply: there is no change set (see step 1), or the change set is a no-op/trivial and obviously correct, or this exact change set was already reviewed in this session. Otherwise proceed. + +## 3. Load guidance docs +Find and read the project's **guidance docs** — root `AGENTS.md`, `CLAUDE.md`, and any in the directories the changed files live in. Use Glob/Grep to locate them (e.g. `**/{AGENTS,CLAUDE}.md`). Treat these as explicit review criteria; cite them when an issue maps to a rule. + +## 4. Summarize the change +Get a concise summary of what the change set does and why (use the diff, plus the commit subject when the commit fallback from step 1 was used), so reviewers share context before diving into the diff. + +## 5. Parallel independent reviews +Launch parallel subagents via the `task` tool (they use whatever model this session was called with; the `explore` agent is read-only). Each subagent reviews one angle **of the changed lines only** and returns a list of issues plus the reason each was flagged (e.g. guidance-doc adherence, bug, historical git context, security): +- **Guidance-doc compliance:** audit the changed lines against AGENTS.md / CLAUDE.md. Guidance docs address the model as it writes code, so not all instructions apply during review. +- **Bug scan:** read the changed lines with only minimal surrounding context; do a shallow scan for obvious bugs and security issues introduced by the change. Focus on large bugs; avoid small issues and nitpicks; ignore likely false positives. +- **Historical context:** read the git blame and history of the changed lines (`git blame`, `git log`) to identify bugs in light of how that code evolved. +- **Comments/intent:** read code comments around the changed lines and ensure the change complies with the guidance in those comments. + +## 6. Confidence scoring +For each issue found in step 5, launch a parallel subagent that takes the issue description and the guidance docs (from step 3) and scores its confidence on a scale from 0–100, using this rubric verbatim: +- **0** — Not confident at all. False positive that doesn't stand up to light scrutiny, or a pre-existing issue. +- **25** — Somewhat confident. Might be real but unverified; stylistic issues not explicitly called out in the guidance docs don't count here. +- **50** — Moderately confident. Verified as real but possibly a nitpick or rare in practice. Relative to the rest of the change set, it's not very important. +- **75** — Highly confident. Double-checked and very likely to matter in practice; directly impacts functionality, or is explicitly mentioned in the relevant guidance doc. +- **100** — Absolutely certain. Double-checked and confirmed real; happens frequently; evidence directly confirms it. + +For issues flagged due to a guidance-doc rule, double-check that the guidance doc actually calls out that issue specifically. + +## 7. Filter +Drop any issue scored <80. If none remain at >=80, report no blocking issues. + +## 8. Re-check eligibility +Confirm the change set still warrants the review before writing up. + +## 9. Report +Present findings concisely in chat. Cite each bug by file path and line range (changed lines only), with 1–2 lines of surrounding context; when an issue maps to a guidance-doc rule, quote the rule. Format: + +``` +### Code review + +Found N issues: + +1. (guidance doc path says "<...>") + +path/to/file.ext:12-18 + +2. (bug due to ) + +path/to/file.ext:40-45 +``` + +Or, if nothing met the threshold: + +``` +### Code review + +No blocking issues found. Checked for bugs and AGENTS.md/CLAUDE.md compliance. +``` + +Examples of false positives (for steps 5 and 6): + +- Pre-existing issues +- Something that looks like a bug but is not actually a bug +- Pedantic nitpicks that a senior engineer wouldn't call out +- Issues that a linter, typechecker, or compiler would catch (e.g. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself — it is safe to assume they will be run separately as part of CI. +- General code quality issues (e.g. lack of test coverage, general security issues, poor documentation), unless explicitly required in a guidance doc +- Issues that are called out in a guidance doc, but explicitly silenced in the code (e.g. due to a lint ignore comment) +- Changes in functionality that are likely intentional or are directly related to the broader change +- Real issues, but on lines outside the change set (unchanged lines) + +Notes: + +- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review. +- Do not fetch anything from the web (no web search or fetch). Use git commands via Bash for history and context instead. +- You must cite each bug by file path and line range. +- Keep output brief. diff --git a/skills/incremental-implementation/SKILL.md b/skills/incremental-implementation/SKILL.md new file mode 100644 index 0000000..6f06ef6 --- /dev/null +++ b/skills/incremental-implementation/SKILL.md @@ -0,0 +1,255 @@ +--- +name: incremental-implementation +description: Delivers changes incrementally in thin, verifiable slices. Use when implementing any feature or change that touches more than one file, or when picking up the next task from a plan. Use when rolling a change out behind a feature flag, when you're about to write a large amount of code at once, or when a task feels too big to land in one step. +--- + +# Incremental Implementation + +## Overview + +Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable. + +## When to Use + +- Implementing any multi-file change +- Building a new feature from a task breakdown +- Refactoring existing code +- Any time you're tempted to write more than ~100 lines before testing + +**When NOT to use:** Single-file, single-function changes where the scope is already minimal. + +## The Increment Cycle + +``` +┌──────────────────────────────────────┐ +│ │ +│ Implement ──→ Test ──→ Verify ──┐ │ +│ ▲ │ │ +│ └───── Commit ◄─────────────┘ │ +│ │ │ +│ ▼ │ +│ Next slice │ +│ │ +└──────────────────────────────────────┘ +``` + +For each slice: + +1. **Implement** the smallest complete piece of functionality +2. **Test** — run the test suite (or write a test if none exists) +3. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check) +4. **Commit** — save your progress with a descriptive message (one logical change per commit; see the atomic-commit guidance below) +5. **Move to the next slice** — carry forward, don't restart + +## Slicing Strategies + +### Vertical Slices (Preferred) + +Build one complete path through the stack: + +``` +Slice 1: Create a task (DB + API + basic UI) + → Tests pass, user can create a task via the UI + +Slice 2: List tasks (query + API + UI) + → Tests pass, user can see their tasks + +Slice 3: Edit a task (update + API + UI) + → Tests pass, user can modify tasks + +Slice 4: Delete a task (delete + API + UI + confirmation) + → Tests pass, full CRUD complete +``` + +Each slice delivers working end-to-end functionality. + +### Contract-First Slicing + +When backend and frontend need to develop in parallel: + +``` +Slice 0: Define the API contract (types, interfaces, OpenAPI spec) +Slice 1a: Implement backend against the contract + API tests +Slice 1b: Implement frontend against mock data matching the contract +Slice 2: Integrate and test end-to-end +``` + +### Risk-First Slicing + +Tackle the riskiest or most uncertain piece first: + +``` +Slice 1: Prove the WebSocket connection works (highest risk) +Slice 2: Build real-time task updates on the proven connection +Slice 3: Add offline support and reconnection +``` + +If Slice 1 fails, you discover it before investing in Slices 2 and 3. + +## Implementation Rules + +### Rule 0: Simplicity First + +Before writing any code, ask: "What is the simplest thing that could work?" + +After writing code, review it against these checks: +- Can this be done in fewer lines? +- Are these abstractions earning their complexity? +- Would a staff engineer look at this and say "why didn't you just..."? +- Am I building for hypothetical future requirements, or the current task? + +``` +SIMPLICITY CHECK: +✗ Generic EventBus with middleware pipeline for one notification +✓ Simple function call + +✗ Abstract factory pattern for two similar components +✓ Two straightforward components with shared utilities + +✗ Config-driven form builder for three forms +✓ Three form components +``` + +Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests. + +### Rule 0.5: Scope Discipline + +Touch only what the task requires. + +Do NOT: +- "Clean up" code adjacent to your change +- Refactor imports in files you're not modifying +- Remove comments you don't fully understand +- Add features not in the spec because they "seem useful" +- Modernize syntax in files you're only reading + +If you notice something worth improving outside your task scope, note it — don't fix it: + +``` +NOTICED BUT NOT TOUCHING: +- src/utils/format.ts has an unused import (unrelated to this task) +- The auth middleware could use better error messages (separate task) +→ Want me to create tasks for these? +``` + +### Rule 1: One Thing at a Time + +Each increment changes one logical thing. Don't mix concerns: + +**Bad:** One commit that adds a new component, refactors an existing one, and updates the build config. + +**Good:** Three separate commits — one for each change. + +### Rule 2: Keep It Compilable + +After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices. + +### Rule 3: Feature Flags for Incomplete Features + +If a feature isn't ready for users but you need to merge increments: + +```typescript +// Feature flag for work-in-progress +const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true'; + +if (ENABLE_TASK_SHARING) { + // New sharing UI +} +``` + +This lets you merge small increments to the main branch without exposing incomplete work. + +### Rule 4: Safe Defaults + +New code should default to safe, conservative behavior: + +```typescript +// Safe: disabled by default, opt-in +export function createTask(data: TaskInput, options?: { notify?: boolean }) { + const shouldNotify = options?.notify ?? false; + // ... +} +``` + +### Rule 5: Rollback-Friendly + +Each increment should be independently revertable: + +- Additive changes (new files, new functions) are easy to revert +- Modifications to existing code should be minimal and focused +- Database migrations should have corresponding rollback migrations +- Avoid deleting something in one commit and replacing it in the same commit — separate them + +## Working with Agents + +When directing an agent to implement incrementally: + +``` +"Let's implement Task 3 from the plan. + +Start with just the database schema change and the API endpoint. +Don't touch the UI yet — we'll do that in the next increment. + +After implementing, run the repository's test and build commands to +verify nothing is broken." +``` + +Be explicit about what's in scope and what's NOT in scope for each increment. + +## Increment Checklist + +After each increment, verify with the repository's own commands: + +- [ ] The change does one thing and does it completely +- [ ] All existing tests still pass (the repository's test command: `npm test`, `./gradlew test`, `pytest`, ...) +- [ ] The build succeeds (the repository's build command) +- [ ] Type checking passes, where the stack has one (`npx tsc --noEmit`, `mypy`, ...) +- [ ] Linting passes (the repository's lint command) +- [ ] The new functionality works as expected +- [ ] The change is committed with a descriptive message + +**Note:** Run each verification command after a change that could affect it. After a successful run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no information. + +## Common Rationalizations + +| Rationalization | Reality | +|---|---| +| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. | +| "It's faster to do it all at once" | It *feels* faster until something breaks and you can't find which of 500 changed lines caused it. | +| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. | +| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. | +| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. | +| "Let me run the build command again just to be sure" | After a successful run, repeating the same command adds nothing unless the code has changed since. Run it again after subsequent edits, not as reassurance. | + +## Red Flags + +- More than 100 lines of code written without running tests +- Multiple unrelated changes in a single increment +- "Let me just quickly add this too" scope expansion +- Skipping the test/verify step to move faster +- Build or tests broken between increments +- Large uncommitted changes accumulating +- Building abstractions before the third use case demands it +- Touching files outside the task scope "while I'm here" +- Creating new utility files for one-time operations +- Running the same build/test command twice in a row without any intervening code change + +## Verification + +After completing all increments for a task: + +- [ ] Each increment was individually tested and committed +- [ ] The full test suite passes +- [ ] The build is clean +- [ ] The feature works end-to-end as specified +- [ ] No uncommitted changes remain + +## See Also + +Per-increment verification is the local check. Before declaring a task done, apply the project-wide Definition of Done as the final gate — the standing bar every increment clears regardless of the task: + +- [ ] Behavior matches the specification / acceptance criteria +- [ ] Tests cover the new behavior and all pass +- [ ] Build, type check, and lint are clean +- [ ] No scope creep or unrelated changes +- [ ] Documentation / changelog updated where the project expects it diff --git a/skills/repo-code-review/SKILL.md b/skills/repo-code-review/SKILL.md new file mode 100644 index 0000000..8433288 --- /dev/null +++ b/skills/repo-code-review/SKILL.md @@ -0,0 +1,83 @@ +--- +name: repo-code-review +description: Review a repository in its current state for bugs, security issues, and guidance-doc (AGENTS.md/CLAUDE.md) compliance. Use when asked to review code, audit the repo/project, or check it before making changes. +--- + +# Repo Code Review + +Provide a rigorous, structured code review of the repository **in its current state**. Follow these steps precisely: + +## 1. Eligibility check +Skip (report "No review needed") if any apply: there is nothing meaningful to review (no source files / empty repo), or this exact scope was already reviewed in this session. Otherwise proceed. + +## 2. Load guidance docs +Find and read the project's **guidance docs** — root `AGENTS.md`, `CLAUDE.md`, and any in directories the review covers. Use Glob/Grep to locate them (e.g. `**/{AGENTS,CLAUDE}.md`). Treat these as explicit review criteria; cite them when an issue maps to a rule. + +## 3. Summarize the repo +Get a concise summary of what the repository is about and its structure, so reviewers share context before diving into code. + +## 4. Parallel independent reviews +Launch parallel subagents via the `task` tool (they use whatever model this session was called with; the `explore` agent is read-only). Each subagent reviews one angle and returns a list of issues plus the reason each was flagged (e.g. guidance-doc adherence, bug, historical git context, security): +- **Guidance-doc compliance:** audit the code against AGENTS.md / CLAUDE.md. Guidance docs address the model as it writes code, so not all instructions apply during review. +- **Bug scan:** read only the relevant files; do a shallow scan for obvious bugs and security issues. Focus on large bugs; avoid small issues and nitpicks; ignore likely false positives. +- **Historical context:** read the git blame and history of the relevant code (`git blame`, `git log`) to identify bugs in light of how it evolved. +- **Comments/intent:** read code comments in the relevant files and ensure the code complies with the guidance in those comments. + +## 5. Confidence scoring +For each issue found in step 4, launch a parallel subagent that takes the issue description and the guidance docs (from step 2) and scores its confidence on a scale from 0–100, using this rubric verbatim: +- **0** — Not confident at all. False positive that doesn't stand up to light scrutiny, or a pre-existing issue. +- **25** — Somewhat confident. Might be real but unverified; stylistic issues not explicitly called out in the guidance docs don't count here. +- **50** — Moderately confident. Verified as real but possibly a nitpick or rare in practice. Relative to the rest of the repo, it's not very important. +- **75** — Highly confident. Double-checked and very likely to matter in practice; directly impacts functionality, or is explicitly mentioned in the relevant guidance doc. +- **100** — Absolutely certain. Double-checked and confirmed real; happens frequently; evidence directly confirms it. + +For issues flagged due to a guidance-doc rule, double-check that the guidance doc actually calls out that issue specifically. + +## 6. Filter +Drop any issue scored <80. If none remain at >=80, report no blocking issues. + +## 7. Re-check eligibility +Confirm the review is still warranted before writing up. + +## 8. Report +Present findings concisely in chat. Cite each bug by file path and line range, with 1–2 lines of surrounding context; when an issue maps to a guidance-doc rule, quote the rule. Format: + +``` +### Code review + +Found N issues: + +1. (guidance doc path says "<...>") + +path/to/file.ext:12-18 + +2. (bug due to ) + +path/to/file.ext:40-45 +``` + +Or, if nothing met the threshold: + +``` +### Code review + +No blocking issues found. Checked for bugs and AGENTS.md/CLAUDE.md compliance. +``` + +Examples of false positives (for steps 4 and 5): + +- Pre-existing issues +- Something that looks like a bug but is not actually a bug +- Pedantic nitpicks that a senior engineer wouldn't call out +- Issues that a linter, typechecker, or compiler would catch (e.g. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself — it is safe to assume they will be run separately as part of CI. +- General code quality issues (e.g. lack of test coverage, general security issues, poor documentation), unless explicitly required in a guidance doc +- Issues that are called out in a guidance doc, but explicitly silenced in the code (e.g. due to a lint ignore comment) +- Changes in functionality that are likely intentional or are directly related to the broader change +- Real issues, but on lines that are outside the review scope + +Notes: + +- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review. +- Do not fetch anything from the web (no web search or fetch). Use git commands via Bash for history and context instead. +- You must cite each bug by file path and line range. +- Keep output brief. diff --git a/skills/resume-coach/NOTICE.md b/skills/resume-coach/NOTICE.md new file mode 100644 index 0000000..73439f1 --- /dev/null +++ b/skills/resume-coach/NOTICE.md @@ -0,0 +1,12 @@ +# Attribution / Notice + +This skill is based on the **"Headless Headhunter" free resume method** by Nick Kroll, +a widely-shared resource for software-engineer job seekers. The core idea — "Keyword + Y +for Bob," the 20-second rule, required role stacks, and formatting guidance — comes from +that original work. + +Original method by Nick Kroll: https://www.youtube.com/@headlessheadhunter + +The text in this SKILL.md was adapted into OpenCode's skill format (YAML frontmatter with +`name`, `description`, `version`, `author`, `tags`). The methodology itself remains free to +use; please credit the original author when applying it publicly. diff --git a/skills/resume-coach/SKILL.md b/skills/resume-coach/SKILL.md new file mode 100644 index 0000000..d05b257 --- /dev/null +++ b/skills/resume-coach/SKILL.md @@ -0,0 +1,130 @@ +--- +name: resume-coach +description: A recruiter-style resume coach that reviews and rewrites resumes for software engineers (and related roles). Uses a proven keyword + plain-language framework ("Keyword + Y for Bob") to turn weak, jargon-filled bullets into hiring-manager-friendly bullets with realistic interview-ratio estimates. +version: 1.0.0 +author: Headless Headhunter methodology +tags: [resume, career, software-engineer, recruiting, job-search] +license: MIT (skill text). Content is based on the "Headless Headhunter" free resume method by Nick Kroll; see NOTICE.md for attribution. +--- + +# Resume Coach — Software Engineer Edition + +You are a blunt, practical recruitment consultant who reviews resumes the way a +real recruiter does under time pressure. Your goal is to help job seekers get +**more interviews**, not just "better" resumes. You speak directly, call out +weaknesses honestly, and give concrete rewrites. + +## Core Philosophy (the whole system in one line) + +> A bullet point gets you an interview only when it contains BOTH: +> **a keyword the hiring manager wants** AND **plain-language impact they can understand.** + +This is called **"Keyword + Y for Bob."** + +- **Keywords** = what the hiring manager looks for (e.g., TypeScript, SQL, CI/CD). + Recruiters don't decide keywords — hiring managers do. If a keyword isn't in + the job description's intent, it doesn't count as a match. +- **"Y for Bob"** = why you used that keyword, explained so simply that a + non-technical hiring manager ("Bob") fully understands the business impact. + **Bob is your imaginary hiring manager:** someone who can't turn on their + monitor without tech support and needs an assistant to send emails in Outlook. + There is a "Bob" in every country — write for *their* Bob, not a technical peer. + +### The two fatal mistakes (both get you rejected) +1. **Keywords only** — the bullet reads like jargon ("failed step triggers a + compensation action instead of leaving bookings in an inconsistent state"). + Bob doesn't understand it → rejected. +2. **Why only, no keywords** — the bullet is plain but irrelevant to what they're + hiring for → rejected. + +✅ You need **both**. A bullet = keyword(s) + a layman-understandable outcome. + +## The 20-Second Rule (how recruiters actually work) +- Recruiters spend roughly **20 seconds** on each resume. +- If it takes longer than 20s to find what you need, they move on. +- Put your strongest keywords and clearest impact in the **first 1–2 sentences**. +- **Formatting matters (~30% of your grade)** — but bad formatting can still pass + if your bullets are strong. Prefer fixing formatting over polishing weak bullets. + +## Required Role Stacks (pick ONE) +If you don't commit to one stack, you get rejected. Choose the one you're applying for: + +| Role | Must-have keywords (in first sentence) | Also common | +|------|----------------------------------------|-------------| +| Full Stack Engineer | TypeScript, JavaScript, HTML, CSS | RESTful API/REST APIs, SQL, cloud, React/React Native, Git/GitHub, CI/CD, Agile, DevOps | +| Java Developer | Java Spring Boot, SDLC, SQL, RESTful API, microservices, CI/CD, OOP | Git/actions, Linux/Unix, agile, scrum, containerization, Docker, Kubernetes, Hibernate, Kafka, AI | +| Cyber Security Engineer | Degrees + certifications (+ clearance as nice-to-have) | Cloud, IAM, NIST, SIEM/SOAR, PowerShell/bash/Python, vulnerability/threat detection & monitoring, communicating to non-technical stakeholders | +| Python Engineer | SQL, Python, Cloud, RESTful API/REST APIs, Git, CI/CD, Docker, Agile, FastAPI | Django/Flask; then EITHER AI-agent stack (LangGraph, MCP, SDK, RAG) OR full-stack | +| Software Engineer Intern | 1–2 primary languages (Java/C++/Go/TypeScript/JavaScript/HTML/CSS/Python/C), SQL/APIs/cloud/AI | Spring Boot (if Java), Docker (if Python); PLUS soft skills below | + +## Formatting Rules +- Clean, simple, professional. **Not flashy.** Flashy = worse chances. +- Education goes at the **TOP** — it's a yes/no checkmark recruiters scan first. + Burying it makes them scroll and lose you seconds. +- Drop the summary section (there are only ~3 valid reasons for one; resume owners aren't among them). +- Contact info must be present but doesn't need to be prominent in bullets. +- **Skills sections do NOT count.** Put keywords inside your experience bullet points. + +## Bullet Point Rules +1. Target **3–6 keywords per bullet** (aim ~5). +2. **No numbers** — except phone number, employment dates, and graduation dates. + Percentages like "improved by 18%" are meaningless to Bob unless you're in sales/management. +3. Every bullet must answer: *What did you do? Why does it matter to the business?* +4. Keep it understandable to a layman. If Bob can't explain it, rewrite it. + +### Bullet formula +> **[Action verb] + [keywords] + [plain-language outcome for Bob].** + +✅ Good: *"Created satellite simulations using Python, RESTful APIs, PostgreSQL, Docker, and CI/CD in an AWS environment to reduce the need for expensive satellite imagery during development."* +❌ Bad (jargon only): *"A failed step triggers a compensation action instead of leaving bookings in an inconsistent state."* + +## The One AI Exception on Numbers +The ONLY time numbers are welcome: if you built **AI infrastructure that many other engineers use to create and run agents**. If not, leave the percentages out. + +## Soft Skills (critical for interns; recommended for everyone) +Include proof of the ability to **work well with others and take direction & criticism.** +- For interns especially — recruiters reject candidates who lack this even if their tech is fine. +- Place it near the top so it's seen within those 20 seconds. + +## Timing Reality Check (say this when relevant) +Most companies don't hire until **~3 months before graduation**. Big tech (Google, FAANG) has its own earlier process; EU/UK have different hiring laws. If the seeker is a student applying too early, tell them honestly — it's often not a resume problem at all. + +## Geographical Note +Keyword lists are ~80% consistent worldwide. The core advice ("Bob," formatting, structure) works everywhere except the Netherlands (where his own method reportedly doesn't apply). + +--- + +## Diagnose Before You Rewrite (the funnel) — @randomrecruiter + +Before rewriting bullets, figure out which stage of the hiring funnel you're stuck at. Your numbers point to the real problem: + +- **100 applications, 0 calls** → your resume (or you're applying to roles you don't match on paper). This is where "Keyword + Y for Bob" and formatting fix things — apply this skill here. +- **Lots of recruiter calls, no second rounds** → comp, location, or how you explain why you're leaving — not bullets. Don't rewrite a resume that never gets past screen. +- **Lots of final rounds, no offers** → you interview fine; someone else is closing better. Rewriting the resume won't help here. + +Most people fix the wrong stage and keep rewriting when the bottleneck isn't the resume at all. Diagnose first, then apply this skill only where it actually applies. + +_Source: @randomrecruiter on X (Oct 12, 2026). Free to use; credit the original._ + +--- + +## How to Use This Skill (your operating procedure) + +When given a resume or bullet points: + +1. **Diagnose which funnel stage you're stuck at** (see "Diagnose Before You Rewrite") so you only rewrite where this skill applies — then identify the target role/stack and confirm they've picked one from the table above. +2. **Scan for keywords in bullets.** Flag any that are only in a "skills" section → move them into experience bullets. +3. **Check each bullet for BOTH parts:** does it have keywords AND Bob-understandable impact? + - If jargon-only → rewrite with plain language + keep the keyword(s). + - If why-only → inject the relevant keyword(s) from the stack list. +4. **Enforce formatting rules:** education on top, no summary, drop flashy styling, remove meaningless numbers. +5. **Estimate an interview ratio** (e.g., "1 in 25 now; with my changes this becomes a 1 in 7–10") to give honest feedback. +6. **Give concrete before/after bullet rewrites.** Never just critique — always show the fix. + +### Output format for your responses +- Start with a blunt overall verdict + estimated interview ratio. +- List top 2–4 flaws (prioritized). +- Provide rewritten bullets using the formula above. +- End with one or two specific next actions. + +Keep it direct, encouraging-but-honest, and always actionable. diff --git a/skills/simplified-technical-english b/skills/simplified-technical-english new file mode 160000 index 0000000..1e148d6 --- /dev/null +++ b/skills/simplified-technical-english @@ -0,0 +1 @@ +Subproject commit 1e148d670cba46685ad2b4c3f2354a637a7fdbbe