Initial commit: global opencode configuration
This commit is contained in:
@@ -0,0 +1,3 @@
|
||||
[submodule "skills/simplified-technical-english"]
|
||||
path = skills/simplified-technical-english
|
||||
url = https://github.com/0xpili/simplified-technical-english.git
|
||||
@@ -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/<name>.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/<name>/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.
|
||||
@@ -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.
|
||||
@@ -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"
|
||||
}
|
||||
@@ -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. <brief description of issue> (guidance doc path says "<...>")
|
||||
|
||||
path/to/file.ext:12-18
|
||||
|
||||
2. <brief description of issue> (bug due to <file and code snippet>)
|
||||
|
||||
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.
|
||||
@@ -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
|
||||
@@ -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. <brief description of issue> (guidance doc path says "<...>")
|
||||
|
||||
path/to/file.ext:12-18
|
||||
|
||||
2. <brief description of issue> (bug due to <file and code snippet>)
|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Submodule
+1
Submodule skills/simplified-technical-english added at 1e148d670c
Reference in New Issue
Block a user