agentscamp 0.1.0

package/content/commands/sync-branch.md

@@ -0,0 +1,138 @@
+---
+description: "Fetch and rebase the current branch onto its base, resolving conflicts and verifying the build."
+argument-hint: "[base branch]"
+allowed-tools: "Bash, Read, Edit"
+---
+
+Bring the current feature branch up to date by rebasing it onto its base. Follow the steps below in order. Stop and report rather than improvise if anything is ambiguous — a rebase rewrites history, so correctness matters more than speed.
+
+## Scope
+
+If `$ARGUMENTS` is provided, treat it as the name of the base branch to rebase onto — supply a bare branch name without a remote prefix (for example `main`, `develop`, or `release-2.0`). If `$ARGUMENTS` is empty, auto-detect the base: prefer the remote's default branch, falling back to `main`, then `master`. Never assume the base — confirm which one you resolved before rebasing.
+
+## Step 1 — Confirm a clean working tree
+
+A rebase must start from a clean tree. Check first.
+
+```bash
+git status --short
+git rev-parse --abbrev-ref HEAD
+```
+
+- If `git status --short` prints nothing, the tree is clean — continue.
+- If there are uncommitted changes, do **not** proceed silently. Either commit them first (use the `commit` workflow) or stash them, and tell the user which you did:
+
+```bash
+git stash push -u -m "sync-branch: pre-rebase stash"
+```
+
+> [!WARNING]
+> If you stash, you must `git stash pop` after the rebase completes (Step 5). Leaving work stashed is a silent way to lose changes. If popping the stash itself conflicts, stop and hand it back to the user.
+
+> [!NOTE]
+> Confirm you are not on the base branch itself. Rebasing `main` onto `main` is a no-op at best; if `HEAD` equals the resolved base, stop and report — there is nothing to sync.
+
+## Step 2 — Fetch the latest base
+
+Update remote refs so you rebase onto current upstream, not a stale local copy.
+
+```bash
+git fetch --all --prune
+```
+
+Now resolve the base branch and record where you started, so you can recover if anything goes wrong.
+
+```bash
+# The remote's default branch, used when $ARGUMENTS is empty
+git remote show origin | sed -n 's/.*HEAD branch: //p'
+
+# Where HEAD is right now — note this hash for recovery
+git rev-parse HEAD
+```
+
+Pick the base in this priority order: `$ARGUMENTS` → remote default branch → `main` → `master`. State the chosen base explicitly before continuing.
+
+## Step 3 — Rebase onto the base
+
+Rebase the current branch onto the **remote-tracking** ref so you incorporate the freshly fetched commits.
+
+```bash
+# Replace <base> with the branch resolved in Step 2
+git rebase origin/<base>
+```
+
+> [!NOTE]
+> Normalize the ref before substituting. If the resolved base already begins with a remote name such as `origin/`, use it verbatim; otherwise prefix `origin/`. This avoids producing an invalid ref like `origin/origin/<base>`.
+
+If the rebase applies cleanly, skip to Step 4. If it stops on a conflict, move to conflict resolution below.
+
+### Resolving conflicts
+
+For each conflicted file, understand **both** sides before editing — do not blindly accept one.
+
+```bash
+# See which files are conflicted (covers all conflict types: UU, AA, DD, AU, etc.)
+git diff --name-only --diff-filter=U
+
+# Inspect a specific conflict, both sides at once
+git diff <file>
+```
+
+- `<<<<<<< HEAD` is the version from the base you are rebasing onto.
+- `>>>>>>> <commit>` is the change from the commit currently being replayed.
+
+Read the surrounding code to grasp intent on each side, then write a resolution that preserves *both* behaviors where they are independent, or the correct one where they genuinely conflict. After editing a file to a coherent state:
+
+```bash
+git add <file>
+git rebase --continue
+```
+
+Repeat until the rebase finishes. If a conflict is genuinely undecidable without product context, abort cleanly and hand it back rather than guessing:
+
+```bash
+git rebase --abort   # restores the pre-rebase state from Step 2
+```
+
+> [!WARNING]
+> Never resolve a conflict by deleting code you do not understand. If a hunk looks load-bearing and you cannot determine which side is correct, stop and ask the user.
+
+## Step 4 — Verify the build and tests
+
+A rebase can produce code that merges textually but breaks logically. Prove the branch still works.
+
+```bash
+# Adapt to the repo's actual scripts
+npm run build
+npm test
+```
+
+If the build or tests fail, the failure was introduced by the rebase — investigate and fix it now, then re-run until green. Do not report success on a red build.
+
+## Step 5 — Restore and report
+
+If you stashed in Step 1, restore that work now:
+
+```bash
+git stash pop
+```
+
+Then summarize the outcome:
+
+- The base branch you rebased onto and how many commits it pulled in.
+- How many of your commits were replayed.
+- Every conflict you resolved and the reasoning for each resolution.
+- The build/test status (must be green).
+- Whether a stash was used and successfully popped.
+
+> [!WARNING]
+> Rebasing rewrites commit hashes, so the local branch and its remote now disagree. Do **not** force-push a shared branch without the user's explicit confirmation. When they confirm, prefer the safe form:
+>
+> ```bash
+> git push --force-with-lease
+> ```
+>
+> `--force-with-lease` refuses to overwrite work someone else pushed while you were rebasing; a bare `--force` does not. Never push at all unless the user asks.
+
+> [!NOTE]
+> If the completed rebase turns out wrong (it finished, but the result is semantically broken), recover with `git reset --hard <the HEAD hash recorded in Step 2>`. This is distinct from `git rebase --abort`, which only works while a rebase is still in progress.

package/content/commands/update-readme.md

@@ -0,0 +1,108 @@
+---
+description: "Update the README to reflect the current scripts, structure, and features of the repo."
+argument-hint: "[section or focus]"
+allowed-tools: "Read, Grep, Glob, Bash, Edit, Write"
+---
+
+Bring the README back in sync with the code. Your job is to find where the README has drifted from reality and correct only those parts — not to rewrite the document. Every claim you keep or add must be backed by something in the repository.
+
+## Scope
+
+`$ARGUMENTS` narrows what you audit.
+
+- A section name (`Installation`, `Scripts`, `Configuration`) means review and fix that section only, leaving the rest untouched.
+- A focus area (`scripts`, `env vars`, `project structure`, `badges`) means reconcile that aspect across the whole README.
+- A path hint (`packages/api`) means update the README that governs that subtree.
+
+If `$ARGUMENTS` is empty, audit the entire top-level README end to end.
+
+> [!NOTE]
+> Do not invent commands, scripts, env vars, or features that are not present in the repo. The README must describe what the code actually does today, not what it should do or once did.
+
+## Step 1 — Read the current README
+
+Find and read every README before changing anything.
+
+```bash
+# Top-level and nested READMEs
+ls README* 2>/dev/null
+find . -iname 'readme*' -not -path '*/node_modules/*' -not -path '*/.git/*'
+```
+
+Read the target README in full. Note its existing headings, ordering, tone, and formatting conventions — you will preserve all of them. Inventory every concrete claim it makes: commands, file paths, ports, env vars, requirements, badges, and links.
+
+## Step 2 — Read the real repo
+
+Ground-truth each claim against the actual project. Pull the facts from the source of truth, not from memory.
+
+```bash
+# Scripts and metadata — the canonical list of commands
+cat package.json        # or pyproject.toml / Cargo.toml / go.mod / Makefile
+
+# Top-level structure the README describes
+ls -la
+find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*'
+
+# Entry points, config, and declared env vars
+ls .env.example 2>/dev/null && cat .env.example
+```
+
+Read the `scripts` block (or `Makefile` targets / task runner) line by line — those are the only commands the README may document. Identify the real entry points (`main`, `bin`, framework config) and any required tooling versions (`engines`, `.nvmrc`, `.python-version`, `rust-toolchain`).
+
+> [!TIP]
+> When a README example references a config file, port, or flag, open that file and confirm the value. A stale port or renamed flag is the most common drift, and the cheapest to verify.
+
+## Step 3 — Diff claims against reality
+
+Build a mental (or written) list of mismatches before editing. Sort each README claim into one of:
+
+- **Stale** — documented but wrong now (renamed script, changed port, moved path, dead link).
+- **Missing** — real and important but undocumented (a new script, a new env var, a new top-level dir).
+- **Phantom** — documented but no longer exists in the code (removed feature, deleted command).
+- **Correct** — matches the code; leave it exactly as is.
+
+> [!WARNING]
+> Resist scope creep. Do not reformat correct sections, reorder existing content, or restyle prose that is already accurate. Touch a line only because the code behind it changed.
+
+## Step 4 — Update only what changed
+
+Edit the README surgically, matching its existing voice and structure.
+
+- Fix **stale** claims to the verified value (correct script name, current port, real path).
+- Add **missing** items into the section where they belong, following the formatting of neighboring entries.
+- Remove **phantom** claims, plus any examples, badges, or links that depended on them.
+- Keep headings, ordering, code-fence languages, and tone identical to the original.
+
+```bash
+# Sanity-check that documented commands actually resolve
+npm run            # lists the real scripts to compare against the README
+```
+
+If the README documents a quickstart, walk the steps in order and confirm each command exists in `package.json` (or the relevant manifest). Replace any command that does not resolve with the real one — never with a guess.
+
+> [!NOTE]
+> If a section is so far out of date that fixing it would mean rewriting it wholesale, flag that section in your report and ask before doing a full rewrite. This command corrects drift; it does not regenerate the README from scratch.
+
+## Report
+
+Summarize the edits as a tight changelog the author can scan:
+
+```markdown
+## README update — <section or "full audit">
+
+### Changed
+- `Scripts`: `npm run serve` → `npm run start` (renamed in package.json)
+- `Quickstart`: dev port 3000 → 3001 (from package.json)
+
+### Added
+- `Scripts`: documented `npm run validate` (was missing)
+- `Configuration`: `DATABASE_URL` from .env.example
+
+### Removed
+- `Features`: dropped "GraphQL playground" — no longer in the codebase
+
+### Left as-is
+- Installation, License (verified accurate)
+```
+
+For every line, name the file that justified the change so the author can verify it. Do not commit or push — leave the working tree for the author to review.

package/content/commands/write-tests.md

@@ -0,0 +1,81 @@
+---
+description: "Generate tests covering the happy path and edge cases for the given target."
+argument-hint: "[file or function]"
+---
+
+Write a focused, high-value test suite for the target supplied in `$ARGUMENTS`. The target may be a file path (e.g. `src/lib/parse.ts`), a specific function or method (e.g. `parseConfig`), or a class. If `$ARGUMENTS` is empty, ask which file or function to cover before continuing.
+
+## Understand the Target
+
+Before writing any tests, build an accurate mental model of what you are testing.
+
+1. Read the target identified by `$ARGUMENTS` and its direct dependencies.
+2. Identify every public entry point: exported functions, methods, and class constructors.
+3. For each entry point, note inputs, outputs, side effects (I/O, mutations, network, time), and thrown errors.
+4. Detect the existing test framework and conventions instead of inventing your own. Check for `jest`, `vitest`, `mocha`, `pytest`, `go test`, etc. in the manifest and look at a neighboring `*.test.*` / `*_test.*` file for style.
+
+> [!NOTE]
+> Match the project's existing patterns exactly: file naming, import style, assertion library, and mocking approach. A test suite that fits the codebase is worth more than one that follows your personal preference.
+
+## Plan the Cases
+
+Enumerate cases before coding so coverage is deliberate, not accidental. Aim for the following categories for each entry point.
+
+### Happy path
+
+The expected, well-formed inputs that represent normal usage. Assert on the concrete return value and any intended side effects.
+
+### Edge cases
+
+Boundary and unusual-but-valid inputs, for example:
+
+- Empty inputs: `""`, `[]`, `{}`, `0`, `null`/`None`, `undefined`.
+- Boundaries: min/max values, off-by-one limits, single-element vs. many-element collections.
+- Unicode, whitespace, very long strings, and duplicate or out-of-order data.
+
+### Error cases
+
+Invalid inputs and failure modes. Assert that the right error type is raised or the documented error result is returned — do not just assert that "something" throws.
+
+```ts
+// Assert the specific failure, not a generic one.
+expect(() => parseConfig("{ bad json")).toThrow(SyntaxError);
+```
+
+## Write the Tests
+
+Produce the suite following these rules.
+
+- Give each test a descriptive name that states the scenario and expected outcome (e.g. `returns 0 for an empty list`).
+- Keep tests independent and deterministic. No shared mutable state and no reliance on execution order.
+- Use the Arrange–Act–Assert shape; keep each test focused on one behavior.
+- Mock only true external boundaries (network, filesystem, clock, randomness). Do not mock the unit under test.
+- Pin nondeterminism: seed RNG and freeze time so runs are reproducible.
+
+```ts
+import { describe, it, expect } from "vitest";
+import { slugify } from "./slugify";
+
+describe("slugify", () => {
+  it("lowercases and hyphenates a normal title", () => {
+    expect(slugify("Hello World")).toBe("hello-world");
+  });
+
+  it("collapses repeated separators", () => {
+    expect(slugify("a  --  b")).toBe("a-b");
+  });
+
+  it("returns an empty string for input with no word characters", () => {
+    expect(slugify("!!!")).toBe("");
+  });
+});
+```
+
+## Verify and Report
+
+1. Run the test suite using the project's test command and confirm every new test passes.
+2. If a test fails, decide whether it revealed a real bug in the target or a flaw in the test, then fix the appropriate side — do not weaken an assertion just to make it pass.
+3. Report a short summary: the entry points covered, the case categories included, and any behavior that looks like a genuine bug.
+
+> [!WARNING]
+> If a test exposes incorrect behavior in the target, surface it explicitly rather than writing the test to match the buggy output. Tests should encode intended behavior, not current behavior.