@chankov/agent-skills 0.3.0 → 0.3.2

package/.versions/0.3.2/skills/using-agent-skills/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Vague idea/need refinement? ──→ idea-refine
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   ├── Need better context? ─────→ context-engineering
+    │   └── Need doc-verified code? ───→ source-driven-development
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    ├── Authoring a new skill/persona? ─→ designing-agents
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- 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..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1. idea-refine                 → Refine vague ideas
+2. spec-driven-development     → Define what we're building
+3. planning-and-task-breakdown → Break into verifiable chunks
+4. context-engineering         → Load the right context
+5. source-driven-development   → Verify against official docs
+6. incremental-implementation  → Build slice by slice
+7. test-driven-development     → Prove each slice works
+8. code-review-and-quality     → Review before merge
+9. git-workflow-and-versioning → Clean commit history
+10. documentation-and-adrs     → Document decisions
+11. shipping-and-launch        → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |
+| Define | spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | incremental-implementation | Thin vertical slices, test each before expanding |
+| Build | source-driven-development | Verify against official docs before implementing |
+| Build | context-engineering | Right context at the right time |
+| Build | frontend-ui-engineering | Production-quality UI with accessibility |
+| Build | api-and-interface-design | Stable interfaces with clear contracts |
+| Verify | test-driven-development | Failing test first, then make it pass |
+| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | code-review-and-quality | Five-axis review with quality gates |
+| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
+| Review | performance-optimization | Measure first, optimize only what matters |
+| Ship | git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | ci-cd-and-automation | Automated quality gates on every change |
+| Ship | documentation-and-adrs | Document the why, not just the what |
+| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |
+| Author | designing-agents | Author a persona, workflow skill, or pi harness |

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # agent-skills changelog
 
+## 0.3.1
+
+### Patch Changes
+
+- Fix: skill resolved the wrong source root on dev machines that have a
+  local clone of `agent-skills`.
+
+  Before this fix, `init` bootstrapped the `guided-workspace-setup` SKILL.md
+  into the workspace at `.pi/skills/...` (or `.claude/skills/...`). When the
+  slash command later loaded the skill, the skill's Step 2 used a "two levels
+  above this file" heuristic to find the source package — but that path
+  resolved to the _workspace_, not the npm package. The skill then fell back
+  to scanning the user's filesystem with `find`, which on a dev machine
+  matched the user's own git clone of `agent-skills`. The clone could be
+  on a different version, mid-edit, or contain experimental skills the user
+  hadn't intended to install.
+
+  The fix:
+
+  1. **`init` now writes `.ai/.agent-skills-bootstrap.json`** containing the
+     absolute path to the source package (the npm cache path, the global
+     install path, or the symlinked clone — whatever `init` was run from).
+  2. **The skill reads this marker first** when resolving the source root.
+     The marker is authoritative; it overrides any older source reference in
+     the install record.
+  3. **The skill never scans the filesystem.** If the marker is missing or
+     stale (path no longer exists), it asks the user for the path explicitly.
+     `find /media/...`, `find ~/repos/...`, etc. are explicitly listed as red
+     flags in the skill's anti-pattern table.
+  4. **The marker file is removed** by Step 10b cleanup alongside the
+     slash commands.
+
+  Affects only the skill's behaviour after `init` — no user-facing CLI
+  changes. Workspaces upgraded from 0.2.x get the marker on their next
+  `npx @chankov/agent-skills init`.
+
 ## 0.3.0
 
 ### Minor Changes

package/bin/lib/bootstrap.js

@@ -25,9 +25,38 @@
 //               (global install / git clone). Warning printed if the
 //               source path looks like an npx cache.
 
-import { existsSync, mkdirSync, copyFileSync, symlinkSync, unlinkSync, lstatSync, rmSync, readdirSync, rmdirSync } from "node:fs";
+import { existsSync, mkdirSync, copyFileSync, symlinkSync, unlinkSync, lstatSync, rmSync, readdirSync, rmdirSync, writeFileSync, readFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 
+// Marker file the skill reads to find the authoritative source root. Written
+// by bootstrap, deleted by cleanupInstaller. Without this, the skill would
+// have to guess the source root from its own SKILL.md location — but bootstrap
+// copies SKILL.md into the workspace, so that heuristic always lies.
+const BOOTSTRAP_MARKER = join(".ai", ".agent-skills-bootstrap.json");
+
+function writeMarker({ workspace, sourceRoot, agent, method }) {
+  const path = join(workspace, BOOTSTRAP_MARKER);
+  const version = readPackageVersion(sourceRoot);
+  const payload = {
+    sourceRoot,
+    version,
+    agent,
+    method,
+    bootstrappedAt: new Date().toISOString(),
+    _comment: "Written by `npx @chankov/agent-skills init`. Read by the guided-workspace-setup skill to locate the source package. Safe to delete; will be regenerated on next init.",
+  };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  return path;
+}
+
+function readPackageVersion(sourceRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(sourceRoot, "package.json"), "utf8"));
+    return pkg.version;
+  } catch { return null; }
+}
+
 // (agent → list of {kind, src, dest}) — kind is just for the report.
 //
 // All installer slash commands are namespaced with `-agent-skills` so they
@@ -184,6 +213,20 @@ export function bootstrap({ agent, sourceRoot, workspace, method, dryRun = false
     }
   }
 
+  // Write the marker file as the LAST step — only after all the bootstrap
+  // files landed successfully. If the marker exists, the skill trusts it
+  // absolutely; if it does not, the skill falls back to safer paths.
+  if (!dryRun && written.length > 0) {
+    try {
+      const markerPath = writeMarker({ workspace, sourceRoot, agent, method });
+      written.push({ kind: "marker", dest: markerPath, method: "write" });
+    } catch (err) {
+      warnings.push(`could not write bootstrap marker: ${err.message}`);
+    }
+  } else if (dryRun) {
+    written.push({ kind: "marker", dest: join(workspace, BOOTSTRAP_MARKER), method: "write" });
+  }
+
   return { written, skipped, removed, warnings };
 }
 
@@ -206,6 +249,18 @@ export function cleanupInstaller({ agent, workspace, dryRun = false }) {
   const planned = plan({ agent, sourceRoot: workspace, workspace });
   const removed = [], kept = [], warnings = [];
 
+  // Marker file goes too — it pointed at a source root that no longer
+  // matters once the install is done.
+  const markerPath = join(workspace, BOOTSTRAP_MARKER);
+  if (existsSync(markerPath)) {
+    if (dryRun) {
+      removed.push(markerPath);
+    } else {
+      try { unlinkSync(markerPath); removed.push(markerPath); }
+      catch (err) { warnings.push(`could not remove ${relative(workspace, markerPath)}: ${err.message}`); }
+    }
+  }
+
   for (const item of planned) {
     if (!existsSync(item.dest) && !isSymlink(item.dest)) {
       kept.push(item.dest); // already gone — count it as a no-op, not an error

package/docs/npm-install.md

@@ -67,6 +67,36 @@ list. Re-run `npx @chankov/agent-skills init` whenever you want
 to the Step 9 confirmation prompt — the skill will record
 `keep-installer: true` in `.ai/agent-skills-setup.md`.
 
+### How the skill finds the source package
+
+`init` writes one extra file alongside the bootstrap: `.ai/.agent-skills-bootstrap.json`.
+This is the **authoritative** record of where the npm package lives:
+
+```json
+{
+  "sourceRoot": "/home/you/.npm/_npx/<hash>/node_modules/@chankov/agent-skills",
+  "version": "0.3.0",
+  "agent": "pi",
+  "method": "copy",
+  "bootstrappedAt": "2026-05-24T..."
+}
+```
+
+When `/setup-agent-skills` runs inside your agent, it reads this marker
+*first* to find the source package. This matters on dev machines where you
+may also have a git clone of `agent-skills` elsewhere — the marker prevents
+the skill from accidentally using that clone instead of the version the
+user just installed via npm.
+
+If the marker is missing or its `sourceRoot` no longer exists (e.g. npx
+cleaned its cache), the skill **asks you explicitly** for the path. It
+never scans your filesystem for other agent-skills repos — that would
+silently pick up forks, stale checkouts, or dev clones that aren't what
+you installed.
+
+The marker is removed by the same Step 10b cleanup that removes the
+slash commands.
+
 | Flag | Default | Purpose |
 |------|---------|---------|
 | `--agent <claude-code\|opencode\|pi>` | auto-detect | Skip the agent prompt |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chankov/agent-skills",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Production-grade engineering skills for AI coding agents. Ships skills, agent personas, slash commands, and pi extensions, with a thin CLI that hands off to the LLM-driven guided setup.",
   "keywords": [
     "ai",

package/skills/guided-workspace-setup/SKILL.md

@@ -34,9 +34,16 @@ Determine which interaction mode this runtime supports, in order of preference:
 
 ### 2. Resolve inputs
 
-Resolve four things. Accept any already supplied in the invocation (the `npx agent-skills init` CLI passes the first three as flags); otherwise ask.
+Resolve four things. Accept any already supplied in the invocation (the `npx @chankov/agent-skills init` CLI passes the first three as flags); otherwise ask.
+
+- **Source root** — the agent-skills package. **Resolution priority (use the first that works; never fall through silently):**
+
+  1. **Bootstrap marker** — read `<workspace>/.ai/.agent-skills-bootstrap.json` if present. Its `sourceRoot` field is authoritative; the CLI wrote it during `init` and it points at the exact package the user's install came from (npm cache, global install, or symlinked clone). Verify the path still exists and contains a `package.json` whose `name` is `@chankov/agent-skills`; if so, use it and **stop**. If the path no longer exists (e.g. npx cache was cleaned), warn the user and continue to step 2.
+  2. **SKILL.md realpath** — only if the marker is missing. If this `SKILL.md` is a symlink, follow it with `readlink`/`realpath` and use the resolved package root. **Do not** use the SKILL.md's *workspace* location (e.g. `.pi/skills/guided-workspace-setup/`) — bootstrap copies the file there, so that path is the workspace, not the source. The realpath only helps in symlink mode.
+  3. **Ask the user explicitly.** Print: *"Source root not found. Run `npx @chankov/agent-skills@latest init` to bootstrap, or paste an absolute path to the package."* Verify the answer is a directory whose `package.json#name` is `@chankov/agent-skills`. **Do not scan the user's filesystem** for other agent-skills repos — that is invasive and produces wrong answers (it will pick up dev clones, forks, or stale copies).
+
+  The install record's `## install-status` may *also* mention an older source root from a previous setup pass; ignore it for resolution. The bootstrap marker overrides it because it reflects what the user just ran. Note the divergence in the Step 9 summary so the user sees the change.
 
-- **Source root** — the agent-skills package. Derive it from this `SKILL.md`'s own location: `skills/guided-workspace-setup/` sits two levels below the package root. When installed via npm, the package root is `node_modules/agent-skills/` or the `npx` cache.
 - **Workspace path** — the target project to configure. Confirm the path exists and is a directory; stop and ask again if it does not.
 - **Coding agent** — `claude-code`, `opencode`, or `pi`. Detect the running agent from the runtime, show it to the user, and let them choose a different one.
 - **Package version** — read `version` from the source root's `package.json`. This is the version that will be stamped into the install record in Step 10, and the right-hand side of every version-aware diff in Step 6.
@@ -266,6 +273,8 @@ Close the report with one line explaining the installer-cleanup outcome:
 | "There's an unfamiliar skill in `.claude/skills/` — the user must have forgotten to uncheck it, I'll remove it." | The removal scope rule exists exactly to prevent this. If the name is not in the agent-skills inventory or not in `## install-status`, it is user-owned; leave it alone and log it as skipped. |
 | "The user wants a clean workspace — I'll prune custom hooks and unrelated MCP entries from `settings.json` too." | Setting-file edits are limited to agent-skills' own hook registrations. Touching anything else silently deletes work that does not belong to this skill. |
 | "`/setup-agent-skills` and `/doctor-agent-skills` are useful — I'll re-install them at the end of apply so the user can re-run them locally." | They are installer commands that the CLI bootstraps and the skill itself cleans up in Step 10b by default. Keeping them is opt-in via `keep` in Step 9. Re-installing them silently undoes the cleanup the user implicitly chose. |
+| "The bootstrap marker is missing — I'll search the user's `~/repos/`, `~/projects/`, and `/media/` for any clone of `agent-skills` to use as the source root." | Scanning the user's filesystem picks up dev clones, forks, half-edited working trees, and stale checkouts that are NOT the package the user installed from. The npm-installed copy is the only authoritative source after `init`. Without the marker, ask the user explicitly — never guess. |
+| "This `SKILL.md` is two levels below the workspace's `.pi/skills/`, so the workspace root must be the source root." | Bootstrap copies `SKILL.md` into the workspace precisely so the slash command can load it. The workspace is the *target* of the install, not the source. Use the marker file to find the real source; resolving from `SKILL.md`'s workspace location always lies. |
 | "The recorded version differs from the current — I'll just refresh everything to the new source without showing the diff." | Conflicting upgrades (user-modified copy + source changed upstream) require the three-way diff to be shown in Step 6, with the row pre-unchecked. Refreshing silently overwrites work the user did between versions. |
 | "The `.versions/<recorded>/` snapshot is missing — I'll pretend the installed copy matches the recorded source and refresh anyway." | A missing snapshot means we cannot compute the three-way diff. The skill must fall back to "treat installed copy as canonical" and surface the missing snapshot in the row's status so the user can decide — never pretend a diff exists. |
 | "The workspace has no `version:` line — I'll silently stamp the current version and move on." | A pre-versioning workspace must be flagged in Step 4 and the user prompted: stamp the current version (assume copies match) or wipe and reinstall. Silent stamping hides a real decision. |
@@ -297,6 +306,9 @@ Close the report with one line explaining the installer-cleanup outcome:
 - A pre-versioning workspace stamped with the current version without prompting the user first.
 - The post-apply `version:` line not matching the package version from Step 2.
 - Step 9 summary missing the installer-cleanup line, or the line stated `keep` as the default.
+- Source root resolved by scanning the filesystem for `agent-skills` repos (`find`, `fd`, `grep -r`, …) instead of using `.ai/.agent-skills-bootstrap.json` or asking the user.
+- Source root resolved by treating `SKILL.md`'s workspace location (`.pi/skills/...` or `.claude/skills/...`) as the package root.
+- The bootstrap marker file (`.ai/.agent-skills-bootstrap.json`) ignored when present, or trusted blindly when the path it names no longer exists.
 - Installer files (`setup-agent-skills`, `doctor-agent-skills`, the `guided-workspace-setup` skill body) left in place without a recorded `keep-installer: true`.
 - `setup-agent-skills` or `doctor-agent-skills` shown as install-menu rows.
 - Step 11 report omitting the one-line installer-cleanup outcome.
@@ -322,6 +334,8 @@ After completing the workflow, confirm:
 - [ ] When the version delta was non-empty, Step 9's summary led with the "Changes since v<recorded> → v<current>" block sourced from `CHANGELOG.md`.
 - [ ] Every `conflicting upgrade` row was rendered with its three-way diff in Step 6 and was not pre-checked.
 - [ ] A pre-versioning workspace was flagged in Step 4 and the user was prompted to stamp or wipe — not silently stamped.
+- [ ] Source root was resolved from `.ai/.agent-skills-bootstrap.json` if present, or from `SKILL.md`'s realpath (symlink mode), or by asking the user — **never** by scanning the filesystem.
+- [ ] If the bootstrap marker named a path that no longer exists, the user was warned and asked for a new path — not silently ignored.
 - [ ] Step 9 summary ended with the installer-cleanup line: states remove-by-default and offers `keep` as the opt-out.
 - [ ] Step 10b ran (or was explicitly skipped because `keep-installer: true`); the installer files are absent from the workspace unless the user opted to keep them.
 - [ ] Step 11 report includes the one-line installer-cleanup outcome.