@chankov/agent-skills 0.3.0 → 0.3.3

package/.versions/0.3.3/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,58 @@
 # agent-skills changelog
 
+## 0.3.3
+
+### Patch Changes
+
+- Ship `scripts/coms-net-server.ts` in the npm tarball.
+
+  The `coms-net` pi harness shells out to this hub server at runtime
+  (`.pi/harnesses/coms-net/index.ts` and its README both reference it),
+  but the file was missing from the `files` allowlist — so users who
+  installed via `npx @chankov/agent-skills init` and tried to start the
+  coms-net harness got `MODULE_NOT_FOUND`.
+
+  Added `scripts/*.ts` to the allowlist (the `.test.mjs` siblings stay
+  out — they're dev-only), and added `scripts/` to `snapshot-version.js`
+  so future `.versions/<x.y.z>/` snapshots include it for the version-
+  aware three-way diff.
+
+## 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/bin/snapshot-version.js

@@ -34,6 +34,10 @@ const ARTIFACT_PATHS = [
   ".pi/skills",
   ".pi/agents",
   ".pi/damage-control-rules.yaml",
+  // scripts/ ships runtime helpers like coms-net-server.ts that the pi
+  // coms-net harness shells out to. Tests under scripts/*.test.mjs stay out
+  // (filtered below) — they're dev-only.
+  "scripts",
   "references",
   "hooks",
 ];
@@ -58,7 +62,10 @@ for (const rel of ARTIFACT_PATHS) {
     recursive: true,
     filter: (srcPath) => {
       const base = srcPath.split("/").pop();
-      return !SKIP_NAMES.has(base);
+      if (SKIP_NAMES.has(base)) return false;
+      // Match what the npm `files` allowlist ships — dev-only tests stay out.
+      if (base.endsWith(".test.mjs") || base.endsWith(".test.js")) return false;
+      return true;
     },
   });
 }

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.3",
   "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",
@@ -46,6 +46,7 @@
     ".pi/skills/",
     ".pi/agents/",
     ".pi/damage-control-rules.yaml",
+    "scripts/*.ts",
     "references/",
     "hooks/",
     "docs/agent-skills-setup.md",